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Programming With DOMAIN 2D Graphics Metafile Resource describes the DOMAIN two- 
dimensional graphics metafile resource system (2D GMR land explains how to use this system in 
developing graphics application programs. Detailed descriptions of the user-callable routines for 
the DOMAIN 2D Graphics Metafile Resource are included in the DOMAIN System Call 
Reference, Volume 1. 

Audience 

This manual is for programmers who use the DOMAIN 2D Graphics Metafile Resource to develop 
application programs. It is assumed that users of this manual have some knowledge of computer 
graphics and have experience in using the DOIVLAIN system. 

Organization of this Manual 

This manual contains fifteen chapters and six appendices. Cross-references in the manual indicate 
the chapter number and the section number. For example, a reference to Section 3.6 refers to 
Chapter 3 and Section 3.6 in the chapter. 

Chapter 1 Presents an overview of the graphics metafile package and a comparison with 

other DOMAIN graphics packages. 

Chapter 2 Describes the DOMAIN display, the 2D GMR™ bitmap, and the effect of 

initialization mode on the display of graphic images. Coordinates systems are 
defined. 

Chapter 3 Presents the structure of 2D GMR application programs, including controlling 

files and segments and instancing segments. The chapter concludes with a 
basic sample program. 

Chapter 4 Describes the draw and fill primitives and explains how to insert them in 

segment. The procedure for displaying all or part of a file or segment is 
described. Instancing and transformation routines are presented with a 
program to illustrate their use. 

Chapter 5 Describes the use of individual attribute commands, explains how to use 

attributes in relation to instancing, and provides a program to illustrate these 
functions. 

Chapter 6 Explains how to insert text and text attributes into a segment. Font families 

and their use are described, along with techniques for creating stroke fonts. 
Programs illustrate the use of routines. 

Chapter 7 Describes the use of the primary segment in displaying a metafile. The chapter 

also includes discussion of segment characteristics and coordiantes data types. 

Chapter 8 Describes the display environment and coordinate systems used with the 

graphics metafile package. Viewing routines are presented with a sample 
program to illustrate their use. 
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Chapter 9 Provides an overview of functions used for interactive editing. The routine for 

changing the editing mode is described and illustrated with a sample program. 

Chapter 10 Describes the following interactive functions: replacing commands, establishing 

a refresh state, picking commands and segments, using input operations and 
event reporting, controlling the cursor, and reading a metafile. Program 
examples illustrate many of these functions. 

Chapter 11 Explains how to extend the 2D GMR to include GPR™outines and user-defined 

primitives. This extension to the 2D GMR package is illustrated with a sample 
program. 

Chapter 12 Describes the routines and the external file format used in generating hard-copy 

output of graphics data. 

Chapter 13 Describes the use of attribute classes and blocks, and explains how to tie 

attribute blocks to attribute classes for the entire display and for individual 
viewports. Programming examples illustrate the use of attribute routines. 

Chapter 14 Describes advanced display techniques including using color and changing the 

viewport border and background. Programming examples illustrate these 
techniques. 

Chapter 15 Describes the use of tags. The chapter also presents techniques for optimizing 

performance in using 2D GMR. Relationships of the DOMAIN graphics 
packages are discussed. 

Appendix A Presents a glossary of graphics terms in relation to the 2D GMR package. 

Appendix B Illustrates the 880 and low-profile keyboards and keyboard charts. 

Appendix C Presents an example of a program that prints out the entire contents of a 

metafile in readable form. 

Appendix D Contains a Pascal program with attributes and instancing. 

Appendix E Contains the programming examples presented in the manual translated into 

C. 

Appendix F Contains the programming examples presented in the manual translated into 

FORTRAN. 

Additional Reading 

For information about using DOMAIN Graphics Primitives, see Programming With DOMAIN 
Graphics Primitives (order no. 005808) and the DOMAIN System Gall Reference, Volume 1 
(order no. 007196) and Volume 2 (order no. (007194). 

For information on DOMAIN Core Graphics, see Programming with DOMAIN Gore Graphics 
(order no. 001955). 

For information about using the DOMAIN system, see the DOMAIN System Gom,mand 
Reference (order no. 002547). For information about the software components of the operating 
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system and user-callable system routines, see the DOMAIN System User's Guide (order no. 
005488). For language-specific information, see the DOMAIN FORTRAN User's Guide (order 
no. 000530), DOMAIN G Language Reference (order no. 002093), and DOMAIN Pascal 
Language Reference (order no. 000792). For information about the high-level language debugger, 
see the DOMAIN Language Level Debugger Reference (order no. 001525). 

On-Line Sample Programs 

The programs from this manual are stored on-line, along with sample programs from other 
DOMAIN manuals. We include sample programs in Pascal, C, and FORTRAN. All programs in 
each language have been stored in master files (to conserve disk space). There is a master file for 
each language. 

To access any of the on-line sample programs, you must create one or more of the following links: 

For Pascal examples: $ CRL ~COM/GETPAS /DOMAIN_EXAMPLES/PASCAL_EXAMPLES/GETPAS 
For C examples: $ CRL "COM/GETCC /DOMAIN_EXAMPLES/CC_EXAMPLES/GETCC 

For FORTRAN examples: $ CRL ~COM/GETFTN /DOMAIN_EXAMPLES/FTN_EXAMPLES/GETFTN 

To extract a sample program from these master files, all you have to do is execute one of the 
following programs: 

To get a Pascal program: $ GETPAS 

To get a C program: $ GETCC 

To get a FORTRAN program: $ GET FTN 

These programs will prompt you for the name of the sample program and the pathname of the 
file to copy it to. Here is a demonstration: 

$ GETPAS 

Enter the name of the program you want to retrieve — STAR_MOVE 

What file would you like to store the program in? — STAR_MOVE . PAS 

Done . 



You can also enter the information on the command line in the following format: 

$ GETPAS <name_of_program_to_retrleve> name _o f _output _ file 
For example, here is an alternate version of our earlier demonstration: 

$ GETPAS STAR_MOVE STAR_MOVE . PAS 

GETPAS, GETCC, and GETFTN will warn you if you try to write over an existing file. 

For a complete list of on-line DOMAIN programs in a particular language, enter one of the 
following commands: 
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$ GETPAS HELP 
$ GETCC HELP 
$ GETFTN HELP 

Documentation Conventions 

Unless otherwise noted in the text, this manual uses the following symbolic conventions. 

UPPERCASE Uppercase words or characters in formats and command descriptions represent 
commands or keywords that you must use literally. 



lowercase 



{} 



CTRL/Z 



Lowercase words or characters in formats and command descriptions represent 
values that you must supply. 

Square brackets enclose optional items in formats and command descriptions. 
In sample Pascal statements, square brackets assume their Pascal meanings. 

Braces enclose a list from which you must choose an item in formats and 
command descriptions. In sample Pascal statements, braces assume their 
Pascal meanings. 

The notation CTRL/ followed by the name of a key indicates a control 
character sequence. You should hold down the <CTRL> key while typing the 
character. 



< > 



Angle brackets indicate a key to be pressed. 



Problems^ Questions, and Suggestions 

We appreciate comments from the people who use our system. In order to make it easy for you 
to communicate with us, we provide the User Change Request (UCR) system for software-related 
comments, and the Reader's Response form for documentation comments. By using these formal 
channels you make it easy for us to respond to your comments. 

You can get more information about how to submit a UCR by consulting the DOMAIN System 
Comm,and Reference manual. Refer to the CRUCR (Create User Change Request) Shell 
command description. You can view the same information on-line by typing: 

$ HELP CRUCR <RETURN> 

For your comments on documentation, a Reader's Response form is located at the back of this 
manual. 
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Chapter 1 
Introduction 



The DOMAIN 2D Graphics Metafile Resource package (hereafter referred to as 2D GMR) and this 
manual are intended for programmers who wish to develop graphics applications packages. The 
DOMAIN 2D GMR package provides a versatile, efficient tool for developing a graphics 
applications system that stores and displays picture data. 

The purpose of this manual is to present concepts, procedures, and examples for users of the 2D 
GMR package. For a complete description of the user-callable routines of the 2D GMR package, 
see Volume 1 of the DOMAIN System Call Reference. The information in this manual is 
intended for programmers with some familiarity with computer-based graphics. The explanations 
and examples are provided for programmers with limited experience, as well as for those who 
have worked extensively with computer graphics. 



1.1. What 2D GMR Provides the Application Developer 

The 2D GMR package is a collection of routines that provide the ability to create, display, edit, 
and store device-independent files of picture data. The package provides routines for developing 
and storing picture data and displaying the graphic output of that data. The 2D GMR package 
provides you with the necessary support to build a graphics system "with a memory." The 
package integrates graphics output capabilities with file handling and editing capabilities. 

The standard form of data storage in this package is a metafile. A metafile is a device- 
independent collection of picture data (vector graphics and text) that can be displayed. The 
metafiles you create are stored and available for you to redisplay, revise, and reuse. They are not 
static copies of display bitmaps; rather, metafiles contain lists of commands used to build a 
graphic image. 

The Table 1-1 summarizes the capabilities of the 2D GMR package and explains what these 
enable you to do. 



1-1 Introduction 



Table 1-1. Capabilities of the 2D GMR Package 



2D GMR Capability: 


Enables you to do this : 


STORAGE 


Graphics system with a memory 


Integrate graphic data, nongraphic 




data, display characteristics. 




editing, file storage, and 




hard-copy output . 


Virtual storage of metafiles 


Store files up to 256 megabytes . 


MODELING/VIEWING 


Commands 


Describe the least divisible element 




of a picture. 


Segmentation 


Group commands that make up separate 




items of a picture; name the items; 




reuse the items . 


Nested segmentation 


Have items include other items. 


Instancing 


Use a single sequence of commands 




multiple times with different 




transformations and attributes applied. 


Scaling 


Make the displayed picture larger 




or smaller. 


Translation 


Move the displayed picture . 


Multiple viewports 


Look at more than one part of the 




picture simultaneously; make changes 




and see the change in each view. 


Flexibility in data types 


Supply coordinate data as 16- or 




32-bit integers or as single-precision 




real numbers . 


A range of commands for drawing 


Draw lines and arcs; draw and 


and filling 


fill circles and polygons 


Attributes 


Establish characteristics 




such as line style and background 




before and during display. 


Blocks of attributes 


Create a data structure that holds a 




collection of values that specify 




attributes . 
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Table 1-1. Capabilities of the 2D GMR Package (continued) 



EDITING 


Editing commands within segments 
while viewing 

Identifying and picking segments 
and commands 


Create interactive application easily; 
change picture details interactively 

Choose the focus of interactivity 


INPUT/OUTPUT 


Accepting coordinate input from 
logical devices 

Output to external file 


Use input devices such as a mouse 
or puck with easy interface 

Transfer data to hard-copy devices 



Within a metafile, commands are grouped into segments. Each segment is a named entity 
consisting of a sequence of commands. A segmentcan be referred to from another segment, in a 
manner analogous to a subroutine call. 

Individual commands within segments of the metafile describe the least divisible components of 
the picture. Commands are categorized as primitive commands, attribute commands, instance 
commands, and tag commands. These commands are defined as follows: 

• Primitive commands: Describe the single least divisible, display able components of a 
picture. These components are, for example, polylines (lists of linked line segments), 
rectangles, circles, and text. 

® Attribute commands: Contain values that specify the manner in which components of 
the picture are to be drawn, for example, the line style or text size. Attribute values 
may be modified individually or in blocks. 

• Instance commands: Cause references to be made to other segments. Instancing 
allows multiple uses of a single sequence of commands, with different transformations 
applied. 

• Tag commands: Provide comments within the file that do not affect the picture. 

Every command is part of some segment. There are no commands outside of all segments. 

Applications programs call 2D GMR routines to edit and display files. These routines are 
categorized into modeling routines and viewing routines: 

• Modeling routines: Control and edit metafiles. 

• Viewing routines: Affect the form in which picture data within metafiles is displayed. 
Hease note our usage of the words "command" and "routine:" 
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® A command is a part of a metafile. 

® A routine is a procedure or function which operates on metafiles. 

® The 2D GMR package is a collection of routines that can edit commands within 
metafiles, or can affect how these commands are to be displayed. Each command is a 
single element of a picture as stored in the metafile. 

The distinction between the 2D GMR package and the metafiles it creates is summarized in Table 
1-2. 

Table 1-2. 2D GMR Package and the Metafile 



DOMAIN 2D Graphics Metafile Resource 

A collection of routines that the programmer can call : 

Modeling Routines: Control and edit Metafiles 

Viewing Routines : Affect how the picture data 

in the metafile is displayed 



A graphics metafile contains segments 

A segment contains commands . 

A command is a primitive command or 
an attribute command or 
an instance command or 
a tag command. 



You call modeling routines to affect the state of the metafile package, or to affect the contents of 
the files. Modeling routines create, open, and close files and segments, and insert, read, copy, and 
delete commands within segments. For each type of command that can occur in a metafile, a 
routine is provided to insert that command into the file; another routine is provided to read the 
parameters of that command from the file. 

Using viewing routines, you may display the images produced by the data in a file. You can then 
edit the file and display the revised image. In all display modes except one (within-GPR), 
coordinates are device-independent. This independence allows convenient display of the output of 
the file (or regions of it) on the screen, or on another device such as a printer. The exception to 
device independence is the display mode called within-GPR. 

Data from input devices, such as a touchpad or a mouse, may be processed and used to help build 
files. 
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The 2D GMR package does not operate directly on bitmaps (unlike other DOMAIN graphics 
packages). Instead, the 2D GMR routines modify either the contents of a metafile or the manner 
in which the metafile is displayed. The 2D GMR package then handles the conversion of the 
metafile to a bitmap for display or for hard-copy output (see Figure l-l). 



Application 

2D GMR Modeling Viewing 
InterfaCG commands Commands 

w w_ 



2D GMR 
Library 
of 
Routines 



Modeling I Viewing 




Figure 1-1. 2D GMR Library of Routines 

The 2D GMR package is a library primarily containing two types of routines: 
modeling and viewing. These two types of routines operate on metafiles as 
follows: 

Modeling routines modify the metafile. Viewing routines read the metafile 
and display it based on viewing parameters. 
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1.2. Data Types 

For flexibility in modeling and for speed in storing data, you may supply coordinate data to the 
2D GMR package in three formats: 

® 16-bit integers 

® 32-bit integers 

® Single-precision real numbers 

Different routines exist to accept data in these different forms, as described in Section 7.3. You 
may supply data in different formats to different commands within a segment. 



1,3. Storage and Display 

The 2D GMR package manages both storage and display of picture data. It differs from graphics 
packages that do not store an image for later display in the same way that a word processor 
differs from a typewriter. 

The structure of the metafile package is analogous to the structure of a word processor or text 
editor, as outlined in Table 1-3. Modeling routines edit metafiles by inserting, changing, and 
inquiring about commands within the metafile. They let you build a file, as when you type 
characters into a text file that is open for editing. 

Viewing routines control the form in which metafiles are displayed. These routines let you look 
at a file, but change only how it is displayed. This is similar to the commands <MOVE> and 
<GROW> used for a window. These routines do not change the contents of a file, but they 
change such characteristics of the displayed image as placement and size. 
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Table 1"3. Graphics Metafile Package and a Word Processor 



2D GMR Package 


Word Processor 


The package manages files of 
picture data. 

Files contain segments. 

Segments contain commands . 

Some modeling routines add 
commands to a file. 

Some modeling routines delete 
commands or copy segments . 

Viewing routines change what 
part of the file is displayed. 


The processor manages files of text. 

Files contain lines. 

Lines contain characters . 

Typing alphanumeric keys 
adds characters to a file . 

Some control keys delete characters 
or copy lines. 

Some control keys change what 
part of the file is displayed. 



lo4. Extendable Package 

The 2D GMR package is extendable. This means that you can use additional routines to mix 2D 
GMR routines calls and GPR routines. The 2D GMR package provides two options to allow you 
to expand it for your application. 

® Within-GPR Mode: A subset of 2D GMR routines can operate in conjunction with 
GPR applications. This allows you to use 2D GMR files within a GPR-based 
application. Within-GPR mode can provide 2D GMR display advantages without 
rewriting existing GPR-based user interfaces. This mode also provides a migration 
path from GPR to 2D GMR (see Chapter 11). 

® User-Defined Commands: Commands that you define within 2D GMR allow you to 
specify additional display routines for commands that you define. 



1.5. Graphics Metafiles and Other DOMAIN Graphics Packages 

The DOMAIN system also has two other graphics packages: DOMAIN Graphics Primitives (GPR) 
and DOMAIN Core Graphics. The graphics primitives library is built into your DOMAIN system. 
The routines (primitives) that make up the library let you manipulate the least divisible graphic 
elements to develop high-speed graphics operations. These elements include lines and polylines, 
text with various fonts, and pixel values. For a detailed description of graphics primitives, see 
the Programming with DOMAIN Graphics Primitives and the DOMAIN System Call 
Reference. 

The DOMAIN system also has an optional Core graphics package. The Core graphics package 
provides a high-level graphics environment in which to build portable graphics application 
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systems. For a detailed description of Core graphics, see the Programming with DOMAIN Core 
Graphics. 

For a description of some of the most significant differences between 2D GMR and GFR, and 
betweeen 2D GMR and Core, see Chapter 15. The distinctive characteristics of the three systems 
are as follows: 

® Graphics Metafiles: Commands are stored in device-independent files of picture 
data. The 2D GMR system lets you create, edit, display, and store picture data. 
Storage and rapid redisplay functions are combined into one package. This allows 
rapid interactive editing and redisplay. Coordinates are device-independent, providing 
flexibility in the development and use of application programs. 

® Graphics Prim.itive8: The function calls cause changes to be made to a bitmap. 
There is no memory of the calls performed except to the limited extent of being able 
to save a static image at any given time. Storing the bitmap in a file does not save 
the sequence of graphics commands that were used to create that bitmap. Therefore, 
redrawing usually requires that an application program itself keep track of and 
reexecute the calls. GPR display coordinates are device-dependent. 

® Core Graphics: The functions in this package conform to an industry standard. The 
functions include modeling and viewing capabilities. The Core package stores 
segments only for redisplay during the same session; no permanent copy is created. 
These segments cannot contain instances of other segments. Coordinates are device- 
independent, providing flexibility in the development and use of application programs. 

The 2D GMR package is distinct from the graphics primitives (GPR) package in this way: GPR 
operations are performed directly to the output device, while 2D GMR operations read, modify, 
or display a metafile (see Figures 1-2 and 1-3). The 2D GMR package initializes the GPR 
package for graphics display purposes; however, the use of 2D GMR and GPR commands within 
a single program is allowed in only one 2D GMR display mode. This mode is discussed in Section 
11.1.2. 
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lo6. Processing Model: Viewing Pipeline 
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Figure 1-4. Graphics Pipeline 

The illustration of the viewing pipeline in Figure 1-4 includes a bitmap. This is a three- 
dimensional array of bits that can be mapped into one-dimensional address space in several ways: 

• Bitmaps in virtual address space may be permanent, residing in the network-wide 
pathname space. 

• Bitmaps may exist in device frame buffers. 

• Bitmaps may have associated color lookup tables. 

In most applications, the user must perform several operations to display part or all of the 
graphics data. The graphics package performs most or all of these steps: 

® Creates graphics and nongraphics databases. 

• Allows modification of databases. 

• Allows display of the graphics data including translation, rotation, scaling, and 
incremental updating of interaction with the display. 

• The display process in a graphics application requires reading graphics commands, 
transforming database coordinates to display coordinates, and displaying graphic 
entities. 

The 2D GMR package performs the steps of the display process as follows: 
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• Viewing routines call a segment to be displayed in a viewport. 

• The display process executes commands in that segment: reads commands, transforms 
coordinates, and performs display operations. 

Instance commands cause commands in another segment to be processed. This can include 
combining the old transformation and the instance transformation. The display process executes 
the command in the instanced segment and then restores the old transformation; the process 
continues executing commands in the instancing segment. 

Basic Interactive Processing Model 

These are the requirements for the basic graphics processing loop: 

• Wait for an input event. 

• Change structures or viewing parameters. 

• Redisplay the scene through the viewing pipeline. 

In a windowing system, these factors can cause complication. Input feedback may have to use the 
display while the pipeline is running. Several windows may want to share the use of the pipeline. 

The viewing pipeline is designed to handle both the processing and the complications. A series of 
graphics processing instructions flows through the pipeline. A pipeline stage in the process acts 
on the instruction in one of the following ways: 

• Ignores the instruction and passes it on. 

• Reads the instruction, updates state (for example, the clipping window), and does not 
pass the instruction on. 

• Transforms the operands and passes the instruction on. 

• Converts it to one or more other instructions and passes them on. 

The pipeline stages are as follows (not all are relevant to 2D GMR): 

• Fetch the instruction. 

• Transform the data. 

• Clip the view space. 

• Execute the projection. 

• Clip the screen space. 

• Process the drawing. 

• Output to the bitmap or display screen. 
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1.7o Strategies for Developing Applications 

This isection provides a brief overview of programming strategies. For a more detailed discussion, 
see Section 15.3. 

The 2D GMR package has many features to aid you in developing application packages. The 
user works in world coordinates that are device-independent. Transformations to images are 
performed as commands are displayed. 

Segmentation includes nested segmentation. This means that instanced segments can themselves 
be instanced. 

The database is optimized for display. 

• The command format is optimized for the graphics hardware. 

• Segment bounds are stored internally. This allows off-screen segments to be skipped 
without reading individual commands. 

• Special commands, such as the rectangle command, are designed for speed. 

2D GMR is in use for a variety of applications. One example is an application that creates a 
building layout, including floor plans, ducting, and text to describe these parts of the layout. In 
such a layout, different segments are used for chairs, tables, and desks. These can then be 
combined by using separate segments for standard rooms and instancing these segments. The 
floor plan, ducts, and wiring can each have its own segment as well. Text can be contained in a 
separate segment. Instancing of segments and characteristics such as visibility of segments can 
change what is displayed. 

2D GMR is highly effective for applications that develop printed-wiring boards. This type of 
application lends itself to the use of separate segments for components and for each collection of 
connections. When a connection crosses layers, the data can be put into multiple segments. 

The approach to applications is to put different classes of data into different segments and to 
make use of characteristics of segments to change the display. When you are dividing a database 
into segments, you need to take the following into consideration: 

• What elements are repeated. 

• What parts of the picture are logically connected. Groups of related segments can be 
visible or pickable. Segments can be assigned different colors or other attributes when 
you instance them. 

• What is the optimum size for fastest output. 
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Chapter 2 

Displaying Graphic Images 



This chapter describes the DOMAIN display, the GM bitmap, and the effect of initialization mode 
on the display of graphic images. Coordinates systems are defined. 



2,1. Elements of the DOMAIN Display 

The DOMAIN display is a bit-mapped raster-scan device consisting of these main components: 
bitmap, display controller, and monitor (see Figure 2-1). 



bitmap 



0000001000000 
0000010100000 
0000100010000 
0001111111000 
0010000000100 
0100000000010 
1000000000001 



scan line 



monitor 




Bitmap 



Figure 2-1. A Raster Graphic System 



The bitmap (also called a frame buffer) is a data structure used to store values for each point or 
pixel in a raster. On monochrome displays, there is one bit per pixel. This one-to-one mapping 
between bits in the bitmap and pixels in the raster has this function: a bit value of 1 turns a pixel 
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on, and a bit value of turns a pixel off. On a color display, more bits are assigned to each pixel 
to specify color through a color table and pixel values. 

GM Bitmap 

With the 2D GMR package, you do not have to write data directly to the bitmap. Instead, you 
use the GM bitmap that is established when you initialize the 2D GMR package. The 
characteristics of this bitmap depend upon the initialization mode. In direct mode, the GM 
bitmap is part of the Display Manager window in which the package was initialized. In borrow 
mode, this is the entire current display. In main-bitmap mode, this is a main-memory bitmap 
(see Section 3.2). 

In 2D GMR, instancing of segments performs the equivalent of bit block transfers and related 
operations. The 2D GMR package allows you to build your graphics database efficiently and to 
reuse data with attributes and transformations applied. 

Display Controller and Monitor 

The display controller is the interface between the bitmap and the display monitor or screen. Its 
function is to read successive bytes of data from the bitmap and convert this data (O's and I's) to 
appropriate video signals, which can then be displayed. The display monitor allows you to view 
the information you have stored in a bitmap. 



2.2o Viewing the Pictures Created by 2D GMR 

This section describes the process of displaying the picture data in the metafile. Display modes 
are explained, along with the following terms particular to the displaying process: GM bitmap, 
viewport, and view. 

GM bitmap is established when you initialize the 2D GMR package. Within the initialization 
routine, you establish one of five display modes: borrow, direct, main-bitmap, no-bitmap, and 

within-GPR. 

• Borrow mode: Uses the entire screen. In borrow mode, the GM bitmap is usually the 
entire screen. 

• Direct mode: Displays within a Display Manager window. In direct mode, the GM 
bitmap is the part of the Display Manager window in which 2D GMR was initialized. 

• Main-bitmap mode: Displays within a bitmap allocated in main memory. The GM 
bitmap is this main-memory bitmap. 

• No-bitmap mode: Allows editing of files without display. There is no GM bitmap. 

• Within-GPR mode: Displays the output of the metafile within a bitmap that you 
initialize using routines of the DOMAIN Graphics Primitives package. There is no 
GM bitmap. 

The viewing routines of the 2D GMR package control the form in which metafiles are displayed. 
When a viewing routine calls for display, the 2D GMR package performs some or all of the 
commands in the metafile. In all display modes except within-GPR, the picture data is displayed 
in viewports which are controlled by the 2D GMR package. When you use within-GPR mode. 
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you must specify the exact placement of the picture data within a graphics primitives bitmap 
under your control. The viewports of the 2D GMR package are not used in this mode. 

In the 2D GMR package, a viewport is part or all of the CM bitmap (see Figure 2-2 through 
Figure 2-6). Each viewport provides a separate view of the output of a metafile or a segment of a 
metafile. You can see different pictures or parts of pictures in different viewports. Moving the 
viewport on the GM bitmap does not change the view; the view moves with the viewport. 

The view is the part of a picture that is currently seen through a viewport. Moving or scaling a 
view affects what you see in the viewport (see Figure 2-2 through Figure 2-6). For example, the 
view may be of a tree. You can move the tree to a new position in the viewport and you can 
change the size of the tree. The viewport remains the same part of the GM bitmap unless you 
explicitly change it. 

To control the appearance of the view by moving or changing the size of the image, you use 
viewing transformation routines. These include routines for translating, scaling, and rotating an 
image in the view. 



viewport 



screen and GM bitmap 

In borrow mode, the GM bitmap is 
usually the whole screen. 



Figure 2-2. Borrow Mode: Screen and GM Bitmap 

You can choose to display any segment within a metafile. You can also make other segments 
referred to (instanced) by this segment be visible or not. Thus, any or all of the segments in a 
file may be displayed in a particular view. For example, the file may contain a picture with a 
house, a sign, and trees. You can specify that you want to see the entire file as a view in a 
viewport. In a different viewport, you may also want to view only the trees, only the sign, or 
only the house without the sign and trees. 

A practical example comes from an architectural application. In developing an architectural 
design with the 2D GMR package, you may want to display all of a floor plan including details 
such as ducting and pipes. Alternatively, you may want a less cluttered view showing the floor 
plan without these details. You can have either one or the other view by choosing the segments 
you want displayed in the viewport you specify. 
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In direct mode, the 

GM bitmap is the user-available 

portion of the DM window. 



Figure 2-3. Direct Modes Screen, GM Bitmap, and Viewport 




-viewport 



GIVI bitmap and screen 



Figure 2-4. Borrow Mode: Viewport 

In using the 2D GMR package, you may want to add data while a program is running. You can 
do this with input routines, which let you generate certain types of data through the keys or 
buttons on a mouse or puck. This data can be used to calculate parameters for routines that 
change the appearance of the display (see Chapter 9). 

You can use pick routines to select a single entity from a file, either a segment or a command. 
As you edit the metafile, you can use the pick routines to select the command you want to 
change. You can also specify that certain elements not be picked. This can protect a basic 
picture while you change some elements in it (see Section 10.9). 
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GM bitmap 



Figure 2-5. Boffow Mode: View Scaled 




GM bitmap 



viewport moved, view the same 



Figure 2-8. Borrow Mode; Viewport and View Moved 



2.3c Coordinate Systems 

The coordinate system of the 2D GMR package has x increasing to the right and y increasing up. 
You can develop a picture in terms of the world coordinates that you are accustomed to using for 
drafting and design (see Figure 2-7). 
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Figure 2-7. 2D GMR Coordinate System 

You may use different coordinates in different segments of the picture you develop. You can then 
specify the relationship of these coordinates when you use instance commands to combine the 
segments. These different coordinate systems provide flexibility in modeling and displaying 
graphic images. 

In the 2D GMR package, you use world coordinates to create and store a collection of data which 
generates a picture. The graphics metafile package converts your device-independent world 
coordinates to device coordinates when it displays the metafile. This allows the same file to be 
displayed on different DOMAIN nodes without requiring changes in your application program. 

This support across devices (device independence) is based on the separation of coordinate systems 
built into the 2D GMR package. You can use world coordinates to define objects in the two- 
dimensional world; the package converts these to device coordinates that relate directly to the 
screen or main-memory bitmap. 
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Developing Application Programs 



This chapter presents the structure of 2D GMR application programs, including controlling files 
and segments and instancing segments. The chapter concludes with a basic sample program. 



3.1. Structure of 2D GMR Application Programs 

The 2D GMR package builds files of picture data stored as collections of 2D GMR commands. 
Each file of picture data is divided into segments, each of which consists of a sequence of 
commands (primitive commands, attribute commands, and references to other segments). Every 
command in a metafile is part of some segment. 

The basic structure of a 2D GMR program is as follows: 
® Initialize the 2D GMR package. 

® Create a file. 

® Create a segment within the file. 

• Put commands in the segment, for example, to draw a rectangle. 

® Display the segment. That is, perform the commands in the segment which make a 
picture appear on the display. 

® Close the metafile. 

® Terminate the 2D GMR session. 

An application program that uses the routines of the 2D GMR package must first initialize the 
2D GMR package. Once the 2D GMR package is initialized, the next step is to create a metafile 
or to open a previously created one. You must open a file to display or to edit it. You can 
create or edit segments within this open file; you can insert and delete commands within the 
segments of the open file. 

Once you establish a segment, you may edit and redisplay it. Editing a segment is analogous to 
editing a line of text with an editor. Every command in a metafile is part of some segment, just 
as every character in a text file is part of some line. 

Segments may contain primitive commands, attribute commands, instance commands, and tag 
commands. 

Primitive commands describe the indivisible, displayable components of a picture, for example, 
polylines (lists of linked line segments), rectangles, circles, and text. 

Attribute commands describe how subsequent components of the picture are to be drawn. For 
example, one attribute can change the line style from solid to dotted. Another attribute can 
change the text size. Attribute values may be modified individually or in blocks. 
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Tag commands are comments in the metafile that do not affect the picture. Tag commands 
provide a convenient way to track information in the database. 

Instance commands cause references to be made to other segments, allowing multiple uses of a 
single sequence of commands with different transformations applied. Instance commands allow 
multiple copies of an object to be conveniently drawn in different locations, at different sizes, or 
with different attributes or color. Instancing of one segment by another segment establishes a 
hierarchy of segments in the metafile. 

Instances can refer to segments which themselves contain instances. This nested segmentation is 
illustrated in Figure 3-1 and Figure 3-2. 

These figures show the structure and display of a file with the following structure. The segment 
at the top of the hierarchy is "scene." When you display segment "scene," the image is made 
using the entire contents of the file, that is the complete hierarchy of that file. Segment "scene" 
instances segment "house." Segment "scene" instances segment "tree" three times. The 
instances include data for scaling and translation. The result is three trees of different sizes in 
different locations. Segment "house" instances and translates segment "window" eight times. 
This results in eight windows at different locations. Segment "house" also instances segment 
"door" and segment "text." This puts the sign "Grand Motel" on the house. See Appendix D 
for the program used to create this figure. 

The hierarchical structure and instancing speed your development of graphic images by allowing 
you to do the following: 

® Reuse segments by changing transformations. 
® View all or part of a metafile. 



SCENE 




WINDOW DOOR TEXT 



Figure 3-1. Example of Hierarchical Structure 
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Figure 3-2. Display of File: Hierarchy with Instancing 



3.2o Controlling the 2D GMR Package 

NOTE: This manual describes the routines of the 2D GMR package in conceptual and 
procedural terms. For a detailed description of the parameters of these routines, see Volume 1 of 
the DOMAIN System Call Reference. 

Functions : 

GM_$INIT 

GM $TERMINATE 



To use the 2D GMR package, you must initialize it. At the end of a program that uses 2D GMR, 
you must terminate the package. 

GM_$INIT initializes the 2D GMR package. Within this routine, you establish one of five 
modes. The choice of mode depends on the purpose of your program and the environment in 
which you want the program to run. For example, direct mode is desirable if you want the 
Display Manager environment to be available while this program is running and displaying. 

The 2D GMR package does not require that you operate directly on a bitmap (a three- 
dimensional array of bits having height, width, and depth). Instead when you establish either of 
two of the five modes (borrow and direct), the 2D GMR package creates a bitmap for display 
purposes. 

The five modes of the 2D GMR package are borrow, direct, main-bitmap, no-bitmap, and within- 
GFR as shown in Table 3-1. 
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Table 3-1. Five Display Modes 



Borrow 
Direct 

Main-bitmap 

No-bitmap 
Within-GPR 



On the full screen, which is temporarily borrowed from the Display Manager 

Within a Display Manager window, which is acquired from the Display 
Manager 

Using a bitmap allocated in main memory without a display bitmap. This 
corresponds to no-display mode in the Graphics Primitives package. 

Without a main-memory or display bitmap 

Using a bitmap specified by routines of the DOMAIN Graphics Primitives 
package 



In borrow mode, the 2D GMR package borrows the full screen and the keyboard from the Display 
Manager and uses the display driver directly through 2D GMR software. All windows disappear 
from the screen. The Display Manager continues to run during this time. However, it does not 
write the output of any other processes to the screen or read any keyboard input until the 2D 
GMR package is terminated. Input you have typed ahead into input pads can be read by the 
related processes while the display is borrowed. 

Borrow mode has the advantage of using the entire screen. However, because borrow mode takes 
over the entire display from the Display Manager, other processes are not immediately available. 

Direct mode is similar to borrow mode, but the 2D GMR package borrows a window from the 
Display Manager instead of borrowing the entire display. The 2D GMR package acquires control 
of the display each time it must generate graphics output within the borrowed window. All other 
processes are handled normally by the Display Manager. 

Direct mode offers a graphics application the performance and unrestricted use of display 
capabilities found in borrow mode. In addition, direct mode permits the application to coexist 
with other activities on the screen. Direct mode is the preferred mode for most interactive 
graphics applications. 

In main-bitmap m,ode, the 2D GMR package creates a main-memory bitmap, but does not create 
a display bitmap. To display the file on the screen, you must terminate main-bitmap mode and 
reinitialize in borrow or direct mode. 

This mode allows you to create user- available bitmaps larger than the full display. 

No-bitmap mode allows you to build a file without a main-memory bitmap or display. No 
viewing operations may be performed in this mode. To display the file, you must terminate no- 
bitmap mode and reinitialize in borrow or direct mode. 

This mode provides the most efficient way to create a metafile from a data base when you do not 
need to be simultaneously monitoring a graphic display of the picture. 
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Within-GPR mode allows you to retain control of the display. You may lay out the display by 
using the routines of the graphics primitives package. To use this mode, do the following: 

® First, initialize the GPR package with GPR_$INIT. 

® You may call GPR routines as you wish. 

® Next, initialize the 2D GMR package using GM_$INIT and specifying within-GPR 
mode. 

® You may call GPR routines or certain 2D GMR routines. All 2D GMR routines that 
establish or edit metafiles are available. A certain set of 2D GMR display routines is 
available (see Section 11.1.2). 

® In this mode, 2D GMR displays to the display bitmap that you have established 
within the graphics primitives package and uses your GPR-specified attribute blocks. 

The 2D GMR viewport routines are not available. 

GM_$TERMINATE closes the 2D GMR package and closes the display. The package closes any 
files and segments which have been left open, saving all changes. 



3.3. Controlling Files 

Functions : 

GM_$FILE_CREATE 
GM_$FILE_OFEN 
GM_$FILE_CLOSE 
GM_$FILE_SELECT 

After initializing the 2D GMR package, you must create and open a file using 
GM_$FILE_ CREATE or open an existing file using GM_$FILE_OPEN. This becomes the 
current file. Within this file, you create segments into which you insert and store commands. 

When you use the routine GM_$FILE_ CREATE, you give the file a pathname; the package 
assigns an identification number as an output parameter of the routine. This identification 
number is an output parameter when you open an existing file using GM_$FILE_OPEN. You 
use this identification number for reference if you have more than one file open at a time. 

To read or edit an existing file, you must open it with GM_$FILE_OPEN. 

You may have more than one file open at a time. When you open a file while another file is 
open, the newly opened file becomes the current file, and the context of the old file (for example, 
current segment, current command) is saved. You may switch among open files using 
GM_$FILE_SELECT. 

You can perform many normal Shell functions on these files. You can copy (cpf), move (mvf), 
and delete (dlf) them, but you cannot concatenate (catf) them. 

When you close the current file, the package is left with no current file; you must then select a 
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file in order to proceed. Upon completion of editing or using a file, you must close it with 
GM $FILE CLOSE. 



3.4. Controlling Segments 

Functions : 

GM_$SEGMENT_CREATE 

GM_$SEGMENT_OPEN 

GM_$SEGMENT_INQ_ID 

GM_$SEGMENT_INQ_CURRENT 

GM_$SEGMENT_INQ_NAME 

GM_$SEGMENT_INQ_COUNT 

GM_$SEGMENT_RENAME 

GM_$SEGMENT_CLOSE 

GM_$SEGMENT_DELETE 

The commands within a file are grouped into segments. You must open a segment before you can 
add commands to it. You can create a new segment with GM_$SEGMENT_ CREATE or open 
an existing segment for redisplay or editing with GM_$SEGMENT_OPEN. This new or newly 
opened segment becomes the current segment. Only one segment per file may be open at a time. 

When you create a segment, you give it a name that must be different from all other segment 
names in the file. The 2D GMR package assigns the segment an identification number. You can 
use this returned segment identification number to create references to (instances of) this segment 
within other segments, or to view this segment (see Section 4.2). The identification number of a 
segment is stored so that it is retained after you terminate the 2D GMR package. 

You also have the option of not naming the segment. To do this, you assign the value to the 
name length parameter. You then use the segment id number to specify an instance of the 
segment. 

Note that viewing operations are independent of editing operations. A segment need not be open 
in order to display it. 

Use GM_$SEGMENT_ CLOSE to close the current segment. You can specify whether or not 
you want to save the changes you have made. 

You can retrieve the name and identification number of the current segment using 
GM_$SEGMENT_INQ_CURRENT. Use GM_$SEGMENT_INQ_ID to retrieve the 
identification number of any existing segment in the current file for which you know the segment 
name. Use GM_$SEGMENT_INQ_NAME to retrieve the name of any existing segment in the 
current file for which you know the identification number. 

You can retrieve the number of segments and maximum segment identification number in a file 
by using GM_$SEGMENT_INQ_ COUNT. This allows you to reopen a file and determine the 
range of segment identification numbers in the file. You can then obtain a list of segment names 
using GM_$SEGMENT_INQ_NAME. 

You may want to rename a segment before, or during the process of, editing it. To do this, use 
GM_$SEGMENT_ RENAME. You may rename any segment, not just the current segment. 
You can also assign the value of zero to the name length parameter and then rely on the segment 
id to identify the segment and to create instances of the segment. 
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GM_$SEGMENT__ DELETE deletes the current segment. You must open a segment before you 
can delete it. If there are any references to (instances of) this segment in other segments of this 
file, the segment is not deleted. 

The routine GM_$SEGMENT_COPY copies the entire contents of another segment into the 
current segment. GM_$SEGMENT_COPY is an editing function and is described in more 
detail in Section 10.11.2. 



3.5. Primary Segment 

Functions : 

GM_$F ILE_SET_PRIMARY_SEGMENT 
GM__$FILE_INQ_PRIMARY_SEGMENT 

The segments in the metafile have a hierarchical structure. The primary segment can be thought 
of as the root for the hierarchy of segments in the metafile. As such, the primary segment is 
assumed to be the start of the picture. When the routine GM_$DISPLAY_FILE is called, the 
primary segment is displayed. 

The first segment you create becomes the primary segment. In Figure 3-1, the primary segment is 
"scene." When you display "scene," you see the entire picture. The segments are instanced 
according to the hierarchy established by the primary segment. 

Using GM _$FILE_ SET _ PRIMARY _ SEGMENT, you can specify that you want another 
segment as the primary segment. For example, with "house" as the primary segment in Figure 
3-1, you see the following upon display: house, door, eight windows, and sign. You do not see 

any trees. 

If you instance the primary segment from a segment which is not itself instanced, the primary 
segment is changed to the instancing segment. If you instance this segment from a segment 
which is itself instanced, the primary segment is changed to the highest-numbered segment not 

instanced by any other segment. 

Use GM_$FILE_SET_PRIMARY_SEGMENT to change the primary segment number. Use 
GM__$FILE_INQ_ PRIMARY _ SEGMENT to retrieve the number of the primary segment. 



3„6o Using World Coordinates 

Coordinate data is supplied to the 2D GMR package as world coordinates. This means that you 
may define coordinates in the most appropriate form for the application. This flexibility allows 
for a separate collection of nongraphics data attached to the graphics data. 

The coordinate data that you supply is device-independent. The capabilities of the display device 
are not a matter of concern at the time you are building the file. 

When the file is displayed, the transformation from the device-independent coordinates stored in 
the file to the display coordinates is performed every time the file is displayed as part of the 
display process. The file coordinates are left alone; the process of viewing does not cause any of 
the coordinates in the database to be changed. 
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It is useful to keep in mind the needs of the nongraphics data when you decide on the form of the 
graphics data. This is up to the application developer who can define whatever coordinates are 
desired for storage in the metafile. The coordinates are transformed in the metafile to the user- 
defined coordinates; they are not transformed to some intermediary coordinates first. 

With care, you may define different coordinate systems in different segments. For example, some 
of the segments that are part of the metafile may have coordinates that are millimeters and 
others that are meters. You must remember, however, at the time you are making reference from 
one segment to another to perform the action that will convert (coerce) from one coordinate 

system to the other (see Section 7.3). 



3.7« Writing 2D GMR Application Programs 

The steps required to produce a 2D GMR application program are presented with a sample 

program in the sections below. 

Including Insert Files 

To write 2D GMR application programs, you must include two insert files for the language you 

are using. The first insert file allows you to use system routines: 

FORTRAN /sys/ins/base.ins.ftn 

Pascal /sys/ins/base.ins.pas 

C /sys/ins/base.ins.c 

The second insert file allows you to use 2D GMR routines: 
FORTRAN /sys/ins/gmr.ins.ftn 

Pascal /sys/ins/gmr.ins.pas 

C /sys/ins/gmr.ins.c 

Declaring Variables 

To use 2D GMR calls, you must declare the variables used as parameters so that they correspond 
to the data types of the DOMAIN system. For information on data types, see the 2D GMR Data 
Types section at the beginning of "2D GMR Calls'* in the DOMAIN System Gall Reference, 

Volume 1. 

Initializing the 2D GMR Package 

To execute 2D GMR calls in an application program, you must first initialize the package. To do 
this, call GM_$INIT in the application program. 

Preparing an Algorithm to Perform a Task 

The next step in the development of a 2D GMR application program is to prepare an algorithm 
using 2D GMR routines to accomplish the task at hand (for an example, see Section 3.8). 
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Terminating a 2D GMR Session 

To end a 2D GMR session, use GM_$TERMINATE. In terminating the session, this routine 
closes any open files and saves the changes. The routine also closes any open segments and saves 
the changes. 



3,8. A Program to Draw a Rectangle 

The program in this section demonstrates how to initialize the 2D GMR package, create a 
metafile, create a segment, and draw a rectangle (see Figure 3-3). 



200,50 



100,30 



Figure 3-3. Drawing a Rectangle 

An additional insert file, /sys/ins/time.ins.pas, is included in this program so that the routine 
time_$wait is available. This routine is not part of 2D GMR, but is useful to keep a figure 
displayed on the screen. 

GM_$INIT initializes the 2D GMR package in direct mode. Bitmap _size, an input parameter 
in GM_$INIT, is assigned dimensions of 1024 x 1024. This ensures that the entire window is 
used as a viewport. When you assign bitmap _ size dimensions of 500 x 500 and run the program 
in a large window, only a portion of the window is used: the top left-most 500 x 500 pixels. The 
input parameter n_ planes is initialized to 8. This is the maximum number of available planes for 
eight-plane color nodes. On monochrome nodes and four-plane color nodes, this value is 
interpreted as 1 or 4, respectively. 

GM_$FILE_ CREATE opens a metafile in the current working directory and makes it current. 
The metafile is opened in overwrite mode, which deletes the previous version if one existed. The 
concurrency parameter, gm_$lw, allows anyone to read the file, but only one person to write to 
the file. 



GM_$SEGMENT. 
rectang_seg. 



CREATE opens a segment within the metafile. The segment is named 
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GM_$RECTANGLE_16 draws a rectangle using 16-bit coordinate data. The coordinates of the 
corners of the rectangle are passed to the routine in two records: ptl and pt2. 

GM_$DISPLAY_FILE displays the contents of the metafile on the screen. This routine will 
display all segments contained within a metafile. Because the file contains only one segment, this 
is the only segment displayed. In this case, GM_$DISPLAY_ SEGMENT would produce the 
same results. 

GM_$SEGMENT_ CLOSE and GM_$FILE_ CLOSE close the segment and the file, 
respectively. 

program draw_rectangle; 

%nolist; 

^include ' /sys/ins/base . ins . pas ' ; 

%include '/sys/ins/gmr . ins .pas' j 

%include ' /sys/ins/time . ins . pas ' ; 

%list; 



CONST 



one_second = 250000; 
flve_seconds =5 * one_second; 
ten seconds = lo * one second: 



VAR 



file_id 
segment_id 

St 

ptl, pt2 

i 

bitmap_size 

pause 

high_plane 



integer; 

gm_$segment_id_t ; 
status_$t; 
gin_$pointl6_t; 
integer32; 
gni_$pointl6_t 
time_$clock_t; 
integer := 8; 



< Array of two 2-byte integers } 
= [1024,1024]; 



BEGIN 



ptl 


.X 


= 


100; 


ptl 


•y 


= 30; 


pt2 


.X 


= 200; 


pt2 


•y 


= 50; 


gmj 


|init( 




gm $direct 




, stream_$stdout 




,bitmap_size 




,high_plane 




,st 




); 


6m_ 


$f ile_create( 






gmf ile* 






SIZEOFCgmfile') 






gm $overwrite 






gm_$lw 






file_id 








st 



< Define the coordinates of tlie 
rectangle to be drawn . > 



i Initialize 2D GMR. > 



"C Create and name a metafile. > 
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); 



gm_$segment_create 

('rectang_seg' 

, sizeof ( ' rectang_seg ' ) 

, segment_ld 

.St 

); 
gni_$rectangle_16 
(ptl 
.pt2 
.false 

.St 

); 



■C Create and name a segment. } 



{ Insert the rectangle . > 



gm_$display_file 
C 

st 
); 



{ Display the file. > 



pause. low32 := f ive_seconds ; 
pause .highie := 0; 
time_$wait( 

time_$relative 

.pause 

.st 

); 



gm_$segment_close ( 
true 
.st 



■C Close the segment.} 



gm_$f ile_close ( 
true 
.st 
); 



"C Close the metafile. > 



gm_$terminate ( 
st 
); 



{ Terminate 2D GMR. > 



END 



Extending the Rectangle Program 

Try changing the operation mode in GM_$INIT to gm_$borrow. If you initialize the bitmap 
with dimensions of 1024 x 1024, the viewport will use the whole display. If the dimensions you 
provide are smaller, only a portion of the display will be used for the viewport. 
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Chapter 4 
Using Basic Modeling Routines 



This chapter describes the draw and fill primitives and explains how to insert them in a segment. 
The procedure for displaying all or part of the file or segment is described. Instancing and 
transformation routines are presented with a program to illustrate their use. 



4.1, Using Draw and Fill Primitives 

Functions : 

GM_$P0LYLINE_2D [16 , 32 , REAL] 
GM_$RECTANGLE_ [1 6 , 32 , REAL] 
GM_$CIRCLE_ C 1 6 . 32 , REAL] 
GM_$CURVE_2D [16,32, REAL] 
GM_$PRIMITIVE_2D [16 , 32 , REAL] 

Draw and fill primitives are modeling routines that insert single primitive commands into the 
current segment of the metafile. When the 2D GMR package reads these commands in the course 
of displaying a file, they cause something to be drawn. The primitive commands include drawing 
line segments, rectangles, circles, and curves, and filling areas. Generally, one primitive command 
is inserted into the metafile each time one of these primitive routines is called. These commands 
include parameters that describe the object to be drawn. 

GM_$POLYLINE_2D[l6,32,REAL] routines insert a command to draw a polyline (list of linked 
line segments). The polyline may be open, closed, or closed and filled. In a closed polyline, the 
first and last points are connected, forming a polygon. 

GM_$RECTANGLE_[16,32,REAL] routines insert a command to draw a rectangle. The 
routine accepts two diagonally opposite corner points of the rectangle. The rectangle command in 
the file may fill the area of the rectangle or draw only the outline of it. 

GM_$CIRCLE_[16,32,REAL] routines insert a command to draw a circle. The routine accepts 
the center point and the radius of the circle. The circle command in the file may fill the circle or 
may draw only the outline of it. 

GM _$ CURVE _ 2D [16, 3 2, REAL] routines insert a command to draw a specified curve. 

GM_$PRIMITIVE_2D[16,32,REAL] routines insert a command to draw a type of displayed 
item that you define. You define the following for the command that is placed into the file: a list 
of points, a list of parameters, and a type number. You connect the type number in the 
command with a display routine that you define using GM_$PRIMITIVE_ DISPLAY _ 2D (see 
Section 11.2). 

This routine is unlike the other draw and fill primitive routines in that you must write the 
display routine that displays these primitive commands. 
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4.2. Displaying Files and Segments 

Functions : 

GM_$D ISPLAY_F ILE 
GM_$D ISPLAY_SEGMENT 

In borrow, direct, and main-bitmap modes, the 2D GMR package produces graphics output in the 
GM bitmap (the screen, Display Manager window, or main-memory bitmap established when the 
2D GMR package was initialized). You can see graphics output or other processes through 
viewports, which are part or all of the GM bitmap. The view is the picture that you can see in a 
viewport. Moving or scaling a view moves or scales what you see through the viewport. 

When you initialize the 2D GMR package, the command GM_$INIT establishes a single 
viewport that fills the GM bitmap. You may want to change the size of the viewport or create 
additional viewports. 

You can divide the GM bitmap into multiple, nonoverlapping viewports. You can specify that 
you want parts of the metafile displayed and moved independently in separate viewports. 

In viewing the graphics output of the 2D GMR package, you can use viewing routines to control 
what is displayed and how it appears. These routines do not affect the contents of the file. You 
can display all of a file or segment, display part of a file or segment, change attributes associated 
with the view, or change the color map. 

When you display an entire file or segment, the view, or picture, is centered in the viewport. 
When you display part of a segment or file, you establish the physical bounds of the part that 
you want displayed. The 2D GMR package then centers and scales that part in the viewport. 
Files or segments may only be displayed in viewports; space on the display that is outside of 
viewports is always empty. 

You can affect the appearance of the picture by inserting attributes into the file individually to 
change, for example, the line style from solid to dashed (see Chapter 5). Or you can change 
attributes more efficiently by inserting an attribute class command into the file. Then, by 
associating different attribute blocks with the class, you can change the view. You can also 
display the same file or segment differently in different viewports. To do this, you associate an 
attribute class with different attribute blocks in different viewports (see Section 13.9). 

You can display the entire file or segment. The picture is automatically centered in the current 
viewport, with a scale calculated so that 95% of the viewport is filled in one dimension and does 
not overflow the viewport in the other dimension. 

GM_$DISPLAY_FILE displays the entire current file in the current viewport. The primary 
segment of the file is displayed. 

GM_$DISPLAY_ SEGMENT displays the specified segment, but not the entire file, in the 
current viewport. 
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4.3o Displaying Part of a File/Segment 

Functions : 

GM_$D I SPLAY_F ILE_P ART 
GM_$DISPLAY_SEGMENT_PART 

You may want to see only part of a graphic image you have developed. For example, you may 
want to see only the wheel of a car, not the entire body of the car that you have been modeling. 

To get part of an image in a view, you use GM__$DISPLAY_ SEGMENT _ PART or 
GM_$DISPLAY_ FILE _ PART to specify, in segment coordinates, the part of the segment (or 
file) you want displayed. That part of the segment (or file) is centered in the current viewport 
with a scale automatically set so that the specified part of the file is displayed as follows: One of 
the two dimensions fills the viewport, and the other dimension does not overflow the viewport. 

This allows you to look at the entire file or segment in one viewport and a smaller part of a file 
or segment in another viewport. The same file or segment can appear in different viewports 
simultaneously (see Figure 4-1). 

GM_$DISPLAY_FILE_PART displays part of the current file in the current viewport. 
Bounds are in segment coordinates of the primary segment. 

GM_$DISPLAY_SEGMENT_PART displays part of the specified segment in the current 
viewport. 



4o4« Using Instancing 

You can use instance routines to insert instance commands into the current segment of a metafile. 
These commands are references to other segments of the metafile. These references, called 
instances, provide an economical and efficient way to reuse a set of commands. An instance 
command includes transformation data (translation, scale, or general two-dimensional 
transformation). This data relates the coordinate system of the instanced segment to the 
coordinate system of the instancing segment. This transformation data is collected by the 2D 
GMR package from the parameters in the instance routine. A segment can contain multiple 
instances of the same segment, with different attributes and transformation matrices. By 
interspersing instance commands and attribute commands, you may display different instances 
with different attributes. 

You can define world coordinates as 32-bit and the coordinates of all or some of the segments as 
16-bit. In instancing a segment multiple times, you point to the data in that segment more than 
once. When you instance a segment, for example, the segment with the tree in Figure 3-2, you 
can scale, rotate, and move it. In addition, you can use attributes to change the line width, line 
style, background, fill value, or other characteristics of the picture. 
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View 1 



View 2 



You can define 
Multiple views. . . 



. . .and 
show them 
anywhere 
on the 
screen. 



.1 

\ I 



Figure 4-1. Multiple Views Shown in Different Viewports 
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When you instance a segment using any GM_$INSTANCE... routine, a copy of the instanced 
segment is not made. Instead, the commands in the instanced segment are displayed, performing 
the logical equivalent of a subroutine call. When you want to change an instanced segment, you 
must open that segment and edit it. You cannot edit an instanced segment from an instancing 
segment. 

Instancing of segments may be nested; an instanced segment may contain instances of other 
segments. However, a segment may not instance itself. An instance may be of any other segment 
in the file, except that circular instancing is prohibited (instancing a segment which directly or 
indirectly instances the current segment). For example, if segment "house" contains an instance 
of segment "door," then you may not insert an instance of segment "house" into segment 
"door." 

A segment must exist before you can instance it. 



4.5. Using Transformations 

Functions : 

GM_$INSTANCE_TRANSLATE_2D [16 . 32 . REAL] 
GM_$INSTANCE_SCALE_2D [16 . 32 . REAL] 

GM_$INSTANCE_TRANSLATE_2D[16,32,REALj routines insert a reference to a segment's 
identification into the current segment. You must give the (x,y) coordinates of the translation to 
apply to the referenced segment. This reference is unsealed and unrotated. 

GM_$INSTANCE_ SCALE _ 2D [16,32,REAL] routines insert a reference to a segment's 
identification into the current segment. You must give the (x,y) coordinates of the translation 
and the scale to apply to the referenced segment. When the command is processed, scaling is 
performed before translation. This reference is unrotated. 

Note that point (0,0) in the coordinates of the instanced segment remains stationary through 
scaling. Therefore, segments that will be transformed in this way should be centered around 
(0,0). 

When displayed, the segment is scaled by the given scale factor, then translated by the amount 
(x,y) in segment coordinates of the instancing segment. 



4.6. A Program Using Primitives and Instancing 
The program in this section draws the design in Figure 4-2. 

The program uses two segments: small _rec and large _rec. The segment small _rec draws a 
small, filled rectangle with dimensions of 100 x 100. The segment large _rec draws a large, 
unfilled rectangle with dimensions of 500 x 500, instances the segment small _rec four times, and 
draws two polylines connecting the four filled rectangles. 

The routine GM_$INSTANCE_ TRANSLATE copies the contents of the instanced segment (in 
this case, small _rec) and translates it to the position provided. This routine is used four times 
to produce four rectangles. 
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Figure 4-2. Four Filled Rectangles within a Box 

The routine GM_$POLYLINE draws a polyline between the end points provided. 

The routine GM_$DISPLAY_ SEGMENT displays the segment large _rec. When this segment 
is displayed, the four instances of small _rec are automatically displayed because they have been 
instanced within large _rec. 



program draw_rectangle: 

%nolist; 

^include * /sys/ins/base . ins . pas ' ; 

%include ' /sys/ins/gmr . ins . pas ' ; 

%include ' /sys/ins/time . ins . pas ' : 

%list; 

CONST 

one_second = 250000; 
five_seconds = 5 * one_second; 
ten seconds = 10 * one second: 



VAR 



file_id 

small_id 

large_id 

st 

ptl, pt2 

i 

bitmap_size 

position 

positions 

pattern 

pause 



integer; 

gm_$segment_id_t ; 

gm_$segment_id_t ; 

status_$t; 

gm_$pointl6_t; 

integer32; 

gm_$pointl6_t := [1024.1024] 

gm_$pointl6_t; 

gm_$point_arrayl6_t; 

gm_$dr aw_pattern_t ; 

time $clock t; 



BEGIN 



gm_$init 



-C Initialize 2D GMR. > 



(gm_$direct 
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, stream_$stdout 

,bltmap_size 

.8 

): 

gin_$f lle_create 

('gmf lie* 

,6 

,gm_$over¥rite 

,gm_$lw 

,file_ici 

.St 



■C Create and name a metafile . > 



ptl .X 
ptl.y 
pt2.x 
pt2.y 



= 100; 
= 100; 
= 200; 
= 200; 



gm_$segment_create 

('small_rec' 

,sizeof ( *small_rec') 

.small_id 

,st 

); 



< Create and name a segment. > 



gm_$rectangle_16 
(ptl 
,pt2 
. true 
,st 
); 



■C Draw a rectangle . > 



gm_$segment_close 
(true 

.St 

); 



{ Close the segment. > 



ptl.x := 100 



ptl.y 
pt2 .X 
pt2.y 



= 100 
= 600 
= 600 



< Define the coordinates of the rectangle > 

< to be drawn. > 



gm_$segment_create 

('large_rec' 

, sizeof ( ' large_rec ' ) 

. large_ld 

.St 

); 

gm_$ dr aw_s ty 1 e 

(gm_$solid 

,4 

, pattern 
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,0 

); 



gm_$rectangle_16 
(ptl 
.pt2 
, false 

-St 



< Draw a rectangle . > 



■C Instance the small rectangle > 
< four times . > 



position. X := 100; 
position. y := 100; 

gm_$instance_translate_2<il6 
(small_id 
, position 
,st 
); 

position. X := 300; 
position. y := 300; 

gm_$instance_translate_2dl6 
(small_id 
, position 
,st 
); 

position. X := 300; 
position. y := 100; 

gm_$instance_translate_2dl6 
Csmall_id 
.position 

.St 

); 



position. X := 100; 
position. y := 300; 

gm_$instance_translate_2dl6 
(small_id 
.position 

.St 

); 



positions [1] .x 
positions [1] .y 
positions [2] .x 
positions [2] .y 



= 300; 
= 300; 
= 400; 
= 400: 



{ Draw two polylines connecting } 
"C the four rectangles . } 



gm_$polyline_2dl6 
(2 
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END. 



, positions 
.false 
, false 

.St 

); 



positions [1] .x 
positions [1] .y 
positions [2] .x 
positions [2] .y 



= 300; 
= 400; 
= 400; 
= 300; 



gm_$polyline_2(il6 
(2 

.positions 
.false 
.false 

.St 

); 

gm_$segment_close 
(true 

.St 

); 



•C Close the segment. > 



gm_$display_segment 
(large_id 

.St 

): 



pause. low32 := f ive_seconds; 



< Keep figure displayed on the > 
•C screen for five seconds. > 



pause. highie := 0; 

time_$wait( time_$relative. pause, st ); 



gm_$f ile_close 
(true 

.St 

); 

gm_$terminate 
( 

St 

); 



< Close the metafile. } 



■C Terminate 2D GMR. > 
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4.7o Instances with Arbitrary Transformations 

Function: 

GM_$INSTANCE_TRANSF0RM_2D [16 , 32 , REAL] 

GM_$INSTANCE_TRANSFORM_2D[16,32,REAL] routines insert a reference to a segment's 
identification into the current segment. Within this routine, you must specify a general 2 by 2 
transformation matrix (that is, rotation, scale, reflection, and skewing) and give the (x,y) 
coordinates of the translation to apply to the referenced segment. When the command is 
processed, the 2 by 2 matrix is applied before the translation. 

A sample transformation matrix follows: 

The input to this routine is a 2x2 transformation matrix, which has the following form: 



I XX 


XY i 


===> 


1 Sx * cos (A) 


Sy * sin (A) | 


where : 


Sx = Scale in 

X direction 

Sy = Scale in 

Y direction 


1 YX 


YY 




1 Sx *-sin(A) 


Sy * cos (A) 1 




A = Angle of 
rotation 



The point (0,0) in the coordinates of the instanced segment remains stationary through reflection, 
rotation, and scaling. Therefore, you should center segments that will be transformed in these 
ways around (0,0). 

When displayed, the segment is rotated and scaled by the 2x2 matrix. The segment is then scaled 
by the given scale factor and then translated by the amount (x,y) in segment coordinates of the 
instancing segment. 

4.8o A Technique Using Arbitrary Transformations 

In the program hotel. pas in Appendix D, the segment "house" is instanced into the segment 
"scene" by using GM_$INSTANCE_ TRANSLATE: 

p[ 1 ] .X := 0; 
p[ 1 ] .y := 0; 

GM_$ INSTANCE_TRANSLATE_2D 1 6 
( sid_house 

. pC 1 ] 
, status 

); 



GM_$INSTANCE_ TRANSLATE allows you to instance a segment without changing the 
segment's scale or orientation. GM_$INSTANCE_ SCALE allows you to change the scale as 
well. (This is used for the trees in the same example program.) Even more general 
transformations are possible with GM_$INSTANCE_ TRANSFORM. 
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The following program fragment replaces the GM_$INSTANCE_ TRANSLATE command (used 
to instance the segment "house" into the segment "scene") with a 
GM_$INSTANCE_ TRANSFORM command. Note the extra argument: 



pc 



1 ] .X := Oj 
1 ] .y := 0; 



gm_$instance_transform_2dl6 
C sici_house 
, matrix 
. p[ 1 ] 
, status 

); 



The argument "matrix" is declared as "gm_$rotate_real2x2_t." (The name of this type is 
misleading in that the matrix may be any 2x2 matrix, not just a rotation matrix. The only 
restriction is that the matrix must have a nonzero determinant.) Some examples are given here 
for reference. Try substituting them into the example program hotel.pas in Appendix D. 

To translate only, set the matrix (to the identity matrix) as follows: 



matrix. XX 
matrix. xy 
matrix. yx 
matrix. yy 



= 1; 
= 0. 
= 0. 

= 1, 



To translate and scale only, set the matrix as follows: 



matrix. XX 
matrix.xy 
matrix. yx 
matrix. yy 



— SOcLx 6 , 

= 0; 
= Oj 
= scale. 



To rotate the house counterclockwise through an angle of 1 radian (about 57 degrees), set the 
matrix as follows: 



matrix. XX 
matrix.xy 
matrix. yx 
matrix. yy 



COS( 1 ) 

SINC 1 ) 

SIN( 1 ) 

COS( 1 ) 



To rotate the house counterclockwise through an angle of 1 radian and scale uniformly, set the 
matrix as follows: 



matrix. XX 
matrix.xy 
matrix. yx 
matrix. yy 



COS( 1 ) * scale; 

- SINC 1 ) * scale, 

SIN( 1 ) * scale, 

COS( 1 ) * scale. 
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To rotate the house counterclockwise through an angle of 1 radian, and scale independently in the 
X and y directions, set the matrix as follows: 



matrix. XX 
matrix. xy 
matrix. yx 
matrix. yy 



COS( 1 ) * scale_x; 

SIN( 1 ) * scale_y; 

SIN( 1 ) * scale_x. 

COS( 1 ) * scale_y, 



To skew the house, as if there were a strong wind blowing from left to right, you might set the 
matrix as follows: 



matrix. XX 
matrix . xy 
matrix. yx 
matrix. yy 
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Chapter 5 
Using Attributes 



This chapter describes the use of individual attribute commands, explains how to use attributes in 
relation to instancing, and provides a program to illustrate these functions. 



5.I0 Using Draw and Fill Attributes 

A metafile can contain attribute commands to change individual attributes. These attributes 
determine such characteristics as the style and pixel value used in drawing lines and filling areas. 
The plane mask attribute allows you to specify which planes of a bitmap can be modified by any 
graphics operation and which planes are protected from modification. 

Each of the routines described in this section inserts a command into the current segment to 
change one attribute. When the segment is displayed, all subsequent primitive commands in the 
segment are displayed with this new value of the changed attribute. This new attribute value also 
applies to the segments subsequently instanced from this segment, but never to the segment that 
instanced this segment (see the examples in Section 5.3). 

Attribute commands inserted into a segment of the metafile take precedence over any other 
means of changing attributes. See Chapter 13 for descriptions of other ways of changing 
attributes. 

The default attribute settings are shown in Table 5-1. 



Table 5~1. Default Attribute Settings 



ATTRIBUTE 


DEFAULT VALUE 


Draw Style 
Draw Value 
Fill Value 
Fill Background Value 


Solid line 

1 

1 

-2 (same as viewport background) 


Fill Pattern 
Text Value 


All I's 
1 


Text Background Value 


-2 (same as viewport background) 


Text Size 


10.0 


Font Family ID Number 
Plane Mask 


1 

All planes can be modified 


Draw Raster Op 


3 (set all destination bit values 
to source bit values) 
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5.1.1. Line Attributes 

Functions : 

GM_$DRAW_VALUE 
GM_$DRAW_STYLE 

Line attributes determine the pixel value, style, and width of lines used in modeling commands. 

GM_$DRAW_ VALUE inserts a command to set the pixel value used when lines are drawn. 

GM_$DRAW_ STYLE inserts a command to set the line style used to display unfilled polylines 
and rectangles. Line style can be either solid or a specified pattern. 

5.1.2. Fill Attributes 

Functions : 

GM_$FILL_VALUE 

GM_$F ILL_BACKGROUND_VALUE 

GM_$F ILL_PATTERN 

Fill attributes determine the appearance of filled areas. 

GM_$FILL_ VALUE inserts a command to set the pixel value used when filling an area. 

GM_$FILL_BACKGROUND_ VALUE inserts a command to set the pixel value used in 
unfilled parts of a pattern that fills an area. For example, in a checkerboard pattern with only 
alternate squares filled, this attribute sets the appearance of the unfilled squares. 

GM_$FILL_ PATTERN inserts a command to set the pattern used to fill the interior of filled 
areas. The default fill pattern is all I's, indicating that the fill value is to be used for all pixels in 
the area being filled. With any other pattern of I's and O's, the fill background value is used for 
pixels corresponding to O's in the pattern. 



5.2o Using Color Map Attributes 

Function: 
GM_$PLANE_MASK 

GM_$PLANE_MASK specifies which planes of a bitmap can be modified by any graphics 
operation and which planes are protected from modification. 

Color map operations are described in Section 14.1. 
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5.2.1. Raster Operation Attributes 

Function: 

GM_$DRAW_RASTER_OP 

Raster operation attributes allow you to specify two conditions that determine what appears in 
the bitmap: 

® What you are drawing. 

® What was there in the GM bitmap. 

There are sixteen different rules for combining old values and values being drawn to create new 
values. A different raster operation code exists for each of these sixteen rules (see Section 5-2). 

A raster operation specifies how to combine source pixel values and destination pixel values to 
form new destination values. The source values are determined by GM_$DRAW_ VALUE. The 
value of each new destination bit is assigned by a Boolean function of the previous value of each 
destination bit and the value of the corresponding source bit. 

Sixteen raster operations form the set of rules for combining bit values. Assigning a raster 
operation code alters no values. The raster operation code controls how values are logically 
combined when a program subsequently draws, fills, or writes text. Table 5-2 lists the op codes, 
symbolic constants, and logical functions for the sixteen raster operations. The symbolic 
constants are available in the insert files for Pascal, FORTRAN, and C Table 5-3 is a truth table 
of the raster operations. 

GM _$DRAW_ RASTER _ OP inserts a command to set the logical raster operation to be 
performed when any nonfilled primitive is drawn. 
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Table 5-2. Raster Operations and Their Functions 



OP 
CODE 


CONSTANT 


LOGICAL FUNCTION 





GM_$ROP_ZEROS 


Assign to all new destination values. 


1 


GM_$ROP_SRC_AND_DST 


Assign source AND destination to new 
destination. 


2 


GM_$ROP_SRC_AND_NOT_DST 


Assign source AND complement of destina- 
tion to new destination. 


3 


GM_$ROP_SRC 


Assign all source values to new destina- 
tion. (Default) 


4 


GM_$ROP_NOT_SRC_AND_DST 


Assign complement of source AND destina- 
tion to new destination. 


5 


GM_$ROP_DST 


Assign all destination values to new 
destination. 


6 


GM_$ROP_SRC_XOR_DST 


Assign source EXCLUSIVE OR destination 
to new destination. 


7 


GM_$ROP_SRC_OR_DST 


Assign source OR destination to new 
destination. 


8 


GM_$ROP_NOT_SRC_AND_NOT_DST 


Assign complement of source AND 
complement of destination to new 
destination. 


9 


GM_$ROP_SRC__EQUIV_DST 


Assign source EQUIVALENCE destination to 
new destination. 


10 


GM_$ROP_NOT_DST 


Assign complement of destination to new 
destination. 


11 


GM_$ROP_SRC_OR_NOT_DST 


Assign source OR complement of 
destination to new destination. 


12 


GM_$ROP_NOT_SRC 


Assign complement of source to new 
destination. 


13 


GM_$ROP_NOT_SRC_OR_DST 


Assign complement of source OR 
destination to new destination. 


14 


GM_$ROP_NOT_SRC_OR_NOT_DST 


Assign complement of source OR complement 
of destination to new destination. 


15 


GM_$ROP_ONES 


Assign 1 to all new destination values. 
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Table 5-3. Raster Operations; Truth Table 



SOURCE 

BIT 

VALUE 


DESTINATION 

BIT 

VALUE 


RESULTANT BIT VALUES FOR THE FOLLOWING OF CODES: 
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 




1 
1 



1 

1 


0000000011111111 
0000111100001111 
0011001100110011 
0101010101010101 



5.3. Using Attributes and Instancing 

Attribute commands change the attributes for all subsequent primitive commands in the segment. 
These changed attributes also apply to all primitive commands in segments subsequently 
instanced from this segment. If an attribute command occurs in a segment that is instanced from 
another segment, it only affects the subsequent commands in instanced segment, never the 
instancing segment. The program fragment below provides an example. 



The following sequence of routines sets up two segments: 

gm_$segment_create(* bottom' , 6, bottomid, status) ; 
gm_$rectangle_16 (pointl . point2, false . status) j 
gm_$draw_value (2, status) ; 
gm_$clrcle_16 (center , radius , false , status) ; 
gm_$segment_close (true , status) ; 

gm_$segment_create('top' ,3, topid, status) ; 
gm_$draw_value (4, status) ; 

gm_$instance_translate_2dl6(bottomid,translate2, status) ; 
gm_$rectangle_16 (points . point4 . false . status) ; 
gm_$segment_close (true . status) ; 

These two segments will then contain the following commands 



•TOP' : DRAW VALUE (4) 

INSTANCE ('BOTTOM') 

RECTANGLE (POINTS , P0INT4 , DONT_FILL) 

'BOTTOM': RECTANGLE (POINTl .P0INT2.D0NT_FILL) 
DRAW VALUE (2) 
CIRCLE (CENTER, RADIUS. DONT FILL) 



When a viewing routine displays segment 'TOP', it does the following: 

® Draws the rectangle (pointl, point2) using draw value 4, since that attribute was set 
by the instancing segment and has not been changed. 
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Draws the circle using draw value 2, the most recent value assigned in this segment. 

Draws the rectangle (points ,point4) using draw value 4, since attribute values changed 
by the instanced segment are restored to their previous values before returning control 
to the instancing segment. 



5.4. A Program with Attributes and Instancing 

The program presented in this section modifies the program presented in Section 4.6. 

The program in this section uses two segments: small _rec and large _rec. The segment 
small _rec draws a small filled rectangle with dimensions of 100 x 100. The segment large _rec 
draws a large unfilled rectangle with dimensions of 500 x 500, instances the segment small _rec 
four times, and draws two polylines connecting the four filled rectangles. 

The routine GM_$INSTANOE_ TRANSLATE copies the contents of the instanced segment (in 
this case, small _rec) and translates it to the position provided. This routine is used four times 
to produce four rectangles. 

The routine GM_$POLYLINE draws a polyline between the endpoints provided. 

The routine GM_$DISPLAY_ SEGMENT displays the segment large_rec. When this segment 
is displayed, the four instances of small _rec are automatically displayed because they have been 
instanced within large _rec. 

The program presented in this section changes the program presented in Section 4.6 as described 
below. 

In this program, the rectangle drawn by the segment small _rec is no longer filled, and the value 
of the line drawing attribute is changed. In the segment large _rec the line drawing attribute is 
changed as well. 

In segment small _rec, the routine GM_$DRAW_ STYLE changes the line style to 
gm_$dotted. This is the simplest way to produce dotted or dashed lines, provided the style is 
acceptable. The parameter gm_$dotted causes every other pixel in the line to be illuminated. 

In segment large _rec, GM_$DRAW_ STYLE also changes the line style. This time the style is 
defined so that each dash is twelve pixels long, and each space between the dashes is four pixels 
long. The line style is defined in the array "pattern" (see the variable declaration section of the 
program). This is an eight-element character array. Char(2#llllllll) sets eight bits on, and 
char(2^1 1110000) sets four bits on and four off. Only sixteen bits of this array are used to define 
the line-style. 

The line attribute used in small _rec (the instanced segment) is not affected by the line attribute 
in large _rec (the instancing segment). 

program draw_rectangle; 

%nolist; 

%inclu(ie ' /sys/ins/base . ins . pas ' ; 

%include */sys/lns/gmr .ins. pas' ; 

^include ' /sys/ins/ t Ime . ins . pas ' ; 

%list; 



Using Attributes 5-6 



CONST 



one_second = 250000; 

five seconds = 5 * one second; 



VAR 



file_ld 

small_id 

large_id 

St 

ptl, pt2 

1 

bitmap_slze 

position 

positions 

pattern 

pause 



integer; 

gm_$segment_id_t ; 
gm_$segment_id_t; 
status_$t; 
gm_$pointl6_t; 
integer32; 
gm_$pointl6_t := 
gm_$pointl6_t; 
gm_$point_arrayl6_t ; 
gm_$draw_pattern_t ; 
time $clock t; 



[1024.1024] 



BEGIN 



gm_$init 

(gm_$direct 

, stream_$stdout 

,bitmap_size 

,8 

, St 

); 

gm_$f ile_create 

Cgmfile' 

,6 

,gin_$overwrite 

,gm_$lw 

.file_id 

. St 

); 



i Initialize 2D GMR. > 



i Create and name a metafile. > 



ptl .X 
ptl.y 
pt2.x 
pt2.y 



= 100; 
= 100; 
= 200; 
= 200; 



< Create and name a segment . ' > 



gm_$segment_create 

( 'small_rec" 

, sizeof ( ' small_rec ' ) 

,small_id 

.St 

); 

gm_$rectangle_16 
(ptl 
.pt2 
.true 

.St 

); 

gm_$segment_close 
(true 



•C Draw a rectangle . > 



< Close the segment. } 
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); 



ptl .X 
ptl.y 
pt2.x 
pt2.y 



= 100; 
= 100; 
= 600; 
= 600; 



gm_$segmeiit_create 
('large_rec' 
, sizeof ( ' large_rec ' ) 
. large_id 
,st 

); 

gin_$dra¥_style 

(gm_$solid 

A 

, pattern 

,0 

,st 

); 



gm_$rectangle_16 
(ptl 
,pt2 
, false 
,st 
); 



< Draw an unfilled rectangle. } 



position. X := 100; 
position. y := 100; 

gin_$instance_translate_2dl6 i Instance and move the small rectangle. > 
(small_id 
, position 
,st 
); 

position. X := 300; 
position. y := 300; 

gm_$lnstance_translate_2dl6 
(small_id 
.position 

.St 

); 

position. X := 300; 
position. y := 100; 

gm_$instance_translate_2dl6 
(small_id 
.position 

-St 

); 
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position. X := 100; 
position. y := 300; 



gm_$instance_translate 2dl6 
(small_id 
.position 

.St 

); 


positions [1] .x 
positions [1] .y 
positions [2] .x 
positions [2] .y 


= 300; 
= 300; 
= 400; 
= 400; 


gm $polyline 2dl6 
(2 

.positions 
.false 
.false 
,st 
); 


positions [1] .x 
positions [1] .y 
positions [2] .x 
positions [2] .y 


= 300; 
= 400; 
= 400; 
= 300; 


gm $polyline 2di6 
(2 

.positions 
.false 
.false 

.St 

); 


gm_$segment_close 
(true 

.St 

); 


gm_$display_segi 
(large_ 
,st 
): 


nent 
id 



{ Close the segment. > 



< Display the figure for five seconds. > 



pause. low32 := f ive_seconds, 
pause. highie := 0; 
time_$wait 

( time_$relative 

. pause 

, st 

); 



gm_$f ile_close 



{ Close the metafile. > 
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(true 

.St 

); 

gm_$terminate < Terminate 2D GMR. > 

( 

St 

): 



END 
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Chapter 6 
Using Modeling Routines: Text 



This chapter explains how to insert text and text attributes into a segment. Font families and 
their use are described along with techniques for creating stroke fonts. Programs to illustrate the 
routines are included. 



60 1. Using Text 

A modeling routine of the 2D GMR package inserts text into the file. The text string with its size 
is inserted into the current segment. 

A font is a related set of characters used for text. In programming terms, a font is data that 
graphically describes a set of related character images. These images may be developed by 
specifying the pixels that make up each character in a bitmap (pixel fonts), or by specifying the 
end points of vectors that make up each character (stroke fonts). Both pixel and stroke fonts can 
be stored in named files on a node. Discussion of both types is included in this chapter. 

Families of text fonts provide a convenient way to display text in different sizes as the displayed 
picture grows and shrinks. A font family is a group of fonts of the same style with a range of 
sizes. During display operations, the 2D GMR package selects a font of the appropriate size from 
the font family. 



6.2, Inserting Text 

Functions : 

GM_$TEXT_2D [16,32. REAL] 

GM_$TEXT_2D[16,32,REAL] inserts a text string into the current segment. The routine 
includes specification of the length and the starting point of the string, in segment coordinates. 

The text is placed as follows: The first character of the text string is placed at the location you 
specify. This means that the origin of this character, as defined in the font, is placed at the 
specified location. Usually, the origin is the lower left-hand corner, excluding descenders. 

You may also specify the direction (in degrees) in which text is to be written. A value of 0.0 
indicates left to right. Other values indicate clockwise rotation. For example, -90 degrees 
indicates bottom to top. 

You may not insert text until you have included at least one font family in the metafile (see 
Section 6.4). 
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6«3. Using Text Attributes 

Functions : 

GM_$TEXT_VALUE 
GM_$TEXT_BACKGROUND_VALUE 
GM_$TEXT_SIZE 
GM_$FONT_FAMILY 

A program can set text attributes. These attributes determine the pixel value, font family, and 
size of text. Attributes can be set individually or in other ways. For a list of default attribute 
settings, see Table 5-1. For a discussion of attribute classes and attributes in viewing operations, 
see Chapter 13. 

GM_$TEXT_ VALUE specifies the pixel value to be used in writing text. 
GM_ $TEXT _ BACKGROUND _ VALUE changes the background pixel value to be used in 
writing text. These attributes are for pixel fonts only. Stroke fonts use GM_$DRAW_ VALUE 
to establish pixel values. 

GM_$TEXT_SIZE specifies the maximum height of a character from the the font family you 
have specified. 

GM_$FONT_ FAMILY specifies the font family to use in writing text. Font families are 
explained below. 



6.4. Identifying Font Families 

Functions : 

GM_$FONT_FAMILY_INCLUDE 
GM_$FONT_FAMILY_INQ_ID 
GM_$FONT_FAMILY_RENAME 
GM_$FONT_FAMILY_EXCLUDE 

A font family is a collection of fonts, each of a different size. The file names of the fonts are 
listed in a font family file. This is an ASCII file, listing file names of fonts, one font per line. 
You may build your own font family files that list names of pixel font files or stroke font files. 

In a font family file, lines which start with "#" are treated as comments and ignored. Currently, 
fonts must be listed in order of size from largest to smallest. For example, a font family file can 
include these lines: 

/sys/dm/f onts/f 9x1 5 
/sys/dm/fonts/f7xl3 
/sys/dm/fonts/f5x9 
/sys/dm/fonts/f5x7 



During a display operation, the 2D GMR package selects a font of the appropriate size from the 
font family. 
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To use a font family in writing text, use GM_$FONT_FAMILY_INCLUDE. You specify the 
font family's pathname and pathname length, and the type of font (pixel or stroke). All fonts 
within the font family file must be of the specified type. The 2D GMR package returns the font 
family identification number. You can then use this identification number in referencing the font 
family. Use GM_$FONT_FAMILY_INQ_ID to retrieve the font family identification 
number of a font family you have already included. 

To eliminate a reference to a font family, use GM_$FONT_ FAMILY _ EXCLUDE. There must 
be no references to the font family you want to exclude. Otherwise, the reference is not 
eliminated. 

A font family identification may be referred to only if it has been included. 

GM_$FONT_FAMILY_RENAME changes the font family file corresponding to this 
identification number. 



6o5. A Program Including Text 

The program in this section draws the design in Figure 6-1. 



This is the top of the rectangle. 



U 









Figure 6-1. Inserting Text 
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This program draws an unfilled rectangle with the text strings "This is the top of the rectangle,** 
and •'This is the side of the rectangle." The routine GM_$FONT_ FAMILY _ INCLUDE 
specifies which font family to use in the metafile. You must create your own font families. For 
example, you can create a Display Manager file with the name font _ families and place the names 
of the fonts you want to use in this file. In the file you could write the following font names that 
are pathnames to specific fonts: 

/sys/dm/fonts/f9xl5 
/sys/dni/fonts/f7xl3 
/sys/dm/fonts/f5x9 
/sys/dm/fonts/f5x7 

The routine GM_$TEXT_SIZE specifies the maximum height of a character from the font 
family that you are using. The value of 14 specified in this program allows the use of text up to 
size 14. The default maximum text size is 10. 

The routine GM_$TEXT_2D16 inserts a text string into the segment at the specified location. 
The first time that this routine is used, the second parameter (rotate) is listed as 0.0. This writes 
the text string horizontally ( "This is the top of the rectangle"). The second time that this 
routine is called, the rotation is set at -90. This causes the text string to be written from bottom 
to top ("This is the side of the rectangle"). 

program draw_rectangle_textj 

%nollst; 

^include ' /sys/ins/base . ins . pas ' ; 

^include '/sys/ins/gmr. ins .pas' j 

%incl\ide * /sys/ins/time . ins . pas ' ; 

%list; 



CONST 



one_second = 250000; 

five seconds = 5 * one second; 



VAR 



BEGIN 



file_id 


integer; 




segment id 
st 


gm_$segment_ld_t; 
: status $t; 




ptl, pt2, point 

i 

bitmap_size 

ffid 

pause 


gm_$pointl6_t; 
: integer32; 
gm_$pointl6_t := [1024, 
integer; 
time $clock t; 


, 1024] 


.IM 

gm_$init 

(gm_$direct 
,1 

,bitmap_size 
,8 


■C Initialize 2D 


GMR.} 






.St 

); 
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gm_$f ile_create 
('gmfile' 

, gm_$over¥rite 

,gm_$lw 

,file_id 

,st 

); 



i Create and name a metafile . } 



gm__$segment_create 
(•rectang_seg' . 
sizeof ('rectang_seg*) 
, segment_id 
,st 
); 



i Create and name a segment. > 



gm_$font_family_include 
( •font_families' 
, SIZEOF('font_families') 
, gm_$pixel 
. ffid 

. St 

); 



-C Load the font family. > 



gm_$text_size 
(14.0 

, St 

); 

point. X := 5; 
point. y := 510; 



< Display a line of text. > 



gm_$text_2dl6 

( point, 0.0 

, 'This is the top of the rectangle.' 

, SIZEOF ('This is the top of the rectangle.') 

, St 

)J 



point. X := 5; 
point. y := 50; 



< Display a line of text. > 



gm_$text_2dl6 
( point 
. -90.0 

, 'This is the side of the rectangle.' 
, SIZEOF('This is the side of the rectangle.') 
, St 

); 



ptl .X 


= 10; 


ptl.y 


= 30; 


pt2.x 


= 400; 


pt2.y 


= 500; 


gm $rectangle 16 


(I 


3tl 



-C Define the coordinates of the > 
< rectangle to be drawn. > 



< Draw the rectangle . > 
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.pt2 
.false 

.St 

); 

gm_$segment_close { Close the segment. > 
(true 

.St 

): 

gin_$ciisplay_f ile i Display the file. > 
(st 
); 

i Display the figure for five seconds. } 
pause . low32 := f ive_seconds; 
pause .highiS := 0; 
time_$¥ait 

( time_$relative 

. pause 

. st 

); 

gm_$f ile_close < Close the metafile. } 
( true 
.st 
); 

gm_$terminate i Terminate 2D GMR. > 
( st 

): 



END 



6.6. Editing Fonts and Font Families 

To change the names of font families already included in a metafile, you must open the metafile 

and use GM_$FONT_ FAMILY _ RENAME. 

Three mechanisms are available for altering the form in which text appears on the screen: 

• You can use a different font family in the metafile. To do this, open the metafile and 
use GM_$FONT_FAMILY_ RENAME. This causes a different font family name to 
be associated with this metafile. 

® You can change the list of fonts which make up a font family. To do this, open the 
ASCII file which lists the fonts in the font family. Edit this ASCII file using the text 
editor. This causes different fonts to be associated with this font family name. 

• You can change the characters in the font. To create and edit stroke fonts, see the 
next section. To edit pixel fonts, use EDFONT, which allows you to interactively edit 
and view character font files. For a description of EDFONT, see the DOMAIN 
System Command Reference manual. 
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6.7o Creating Stroke Font Files 

A stroke font file is a metafile. It is created and edited using normal metafile routines. 

8.7.1. Defining Characters 

The characters or icons of a stroke font are made up of primitive commands, like any other 
metafile segment. Each character has its own segment in a metafile. The set of characters (the 
font) is stored in a metafile. 

You may define any or all of the 256 possible characters in a font, including the space character. 
The segment name for each character must be a one-character name. This name must be either 
the character that the segment defines or a nonprintable ASCII value for special icon definition. 

A stroke font metafile may not contain attributes or instances, only primitives and tags. If any 
attribute or instance command is found in a stroke font segment, the specified character is 
treated as nonexistent. 

When a text string is displayed, each character is displayed based on the following: 

• Y = is the baseline along which text is displayed. 

• Y = 1000 is to be scaled to the current text size. 

• The start of the next character is defined as the start of the old character, plus the 
horizontal size of the old character, plus an intercharacter spacing of 200. 

8.7.2. Defming Character Width 

The default width of a character is the maximum x value used in defining the segment (segment 
bounds). In a segment for an individual character, you can use a tag command to change the 
width of a character. A tag consists of WIDTH followed by a number to indicate the character 
width you want. (Separate the word WIDTH and the value by a space.) This tag command 
must precede any other commands in the segment. Descriptor tags in a stroke font file must be 
entered in the file in capital letters, for example, WIDTH. 

The tag WIDTH is also used to define the space character (chr(32)), which contains only the 
WIDTH tag command. If a text string being displayed includes a nonexistent character (one for 
which there is no segment), the space character is displayed instead. If you have not defined a 
space character, nothing is displayed, and words within a string will run together. 
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8.7.3. Font Defaults 

To set values applicable to every character and icon in the stroke font file, you can create an 
additional segment with the name DATA (the length of the segment name = 4). In this segment, 
only certain tag commands are recognized. 

The following is a list of key words and their default values. You can change these values using 
tag commands in the segment DATA. 



Key Word 


Default Value 


HEIGHT 


1000 


CHAR _ OFFSET 


200 


MIN SIZE 






Definition of Terms 

® HEIGHT: The maximum y value above the origin, in coordinates of the character 
segment. This value is used to scale text in this font to fit the current text size. 

• CHAR_ OFFSET: The x offset between the end of a character and the start of the 
next character, in coordinates of the character segment. This value is used for spacing 
between characters in a string. 

® MIN_SIZE: The minimum height, in pixels, for which to use this font. If a 
transformation causes the character HEIGHT on the screen to be less than 
MIN_SIZE, this font is not used. 

The DATA segment need not appear in any specific location in the stroke file. You may omit the 
DATA segment if you wish to use default values. 



6.7.4. Limitations 

The following limitations apply to the maximum number of font families and the maximum 
number of font files within families and overall. 

You may specify a maximum of eight font families. Overall the font families, you may specify a 
maximum of 32 font files. If different font families specify the same font file, 2D GMR does not 
recognize the redundancy, so each reference counts as a separate font file. 

A font family of stroke text may specify only two stroke text font files; a font family of pixel text 
may specify any number of pixel text font files (up to the overall limit of 32 font files). 



6.8. A Procedure to Define a Font 

This program example defines a stroke font. To define a font with equal spacing between 
characters, tag each character with an equal WIDTH and center each character definition between 
and WIDTH in x. Adjust the CHAR _ OFFSET accordingly. 

To define a proportionally spaced font, set the minimum x value to and assign a value to 
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.X 


= 0; 


■ y 


= 0; 


.X 


= 400; 


•y 


= 1000; 


.X 


= 800; 


• y 


= 0; 


die 


^3, poin 


.X 


= 200; 


• y 


= 500; 


.X 


= 600; 


• y 


= 500; 



WIDTH for each character. (Use uppercase for the value WIDTH). Alternatively, you can omit 
the specification of WIDTH. In this case, the maximum x of the character is the WIDTH, and 
the CHAR _ OFFSET is used to separate the characters in a string. 

The following examples show the use of tags with character and icon definition: 

gm_$segment_create('A' , 1. segment_id, st) ; 

point_array [1] 

point_array [1] 

point_array [2] 

point_array [2] 

point_array [3] 

polnt_array [3] 

gm_$polyllne_2dl6(3, point_array, false, false, st) 

point_array [1] 

point_array [1] 

point_array [2] 

point_array [2] 

gm_$polyline_2dl6(2, point_array, false, false, st) 

gm_$segment_close(true, st) ; 

gin_$segment_create( ' ', 1, segment_id, st) ; 
gin_$tag(' WIDTH 800'. 9, st) ; 
gm_$segment_close(true, st) ; 

gm_$segment_create(*DATA' , 4, segment_id, st) ; 
giii_$tag('MIN_SIZE 15', 12, st) ; 
gm_$segment_close(true, st) ; 



6o9. Program With Stroke and Pixel Fonts 

The following program loads a pixel font family file and a stroke font family file and then shifts 
back and forth between them using an attribute block and attribute class command. The 
purpose of this program is to illustrate the use of the two types of text. The attribute block and 
attribute class command provide an easy way to change text size. For a discussion of attribute 
blocks and attribute classes, see Chapter 13. 

The first part of the program shows the effect of changing text size with pixel and stroke fonts 
One segment containing text is created and then redisplayed with different text sizes. The text 
size is changed using an attribute block. 

The second part of the program creates a new segment and then instances the original text 
segment using GM_$INSTANCE_TRANSFORM_2D16. The instance command is replaced 
again and again with different angles of rotation to illustrate the effect on the text. The program 
shows that rotated pixel text snaps to the nearest 90 degrees, whereas stroke text rotates 
smoothly. 

PROGRAM text; 

%NOLIST; 

%INCLUDE '/sys/ins/base.ins.pas' ; 
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%INCLUDE * /sys/ins/gmr . ins . pas ' ; 

%INCLUDE Vsys/lns/pfm. ins .pas' : 

%INCLUDE Vsys/ins/time. ins. pas' 
%LIST; 

CONST 



acxass i 
second 
cos_delta 
sin delta 



= IJ 

= 500000; 

= COS( 0.25 ) 

= SIN( 0.25 ) 



VAR 



Status 

sid_text 

sid_top 

file_id 

ffid_pixel 

ffid_stroke 

ablock_id 

P 

q 

dbounds 
i 

J 

text_size 

text_size_delta 

rotate 



status_$t; 

gni_$segnient_id_t ; 

gm_$segment_id_t: 

INTEGER ; 

INTEGER; 

INTEGER; 

INTEGER; 

gm_$pointl6_t; 

gm_$pointl6_t; 

gm_$boundsreal_t ; 

INTEGER; 

INTEGER; 

REAL; 

REAL; 

gm_$rotate_real2x2_t . 

gm $pointl6 t; 



pause 



time $clock t; 



PROCEDURE check 

( IN status : status_$t 
); 

BEGIN 

IF status. all <> status_$ok 
THEN pfm_$error_trap( status ) 
END; 



BEGIN 



p.x := 1024; 
p.y := 1024; 

gm_$init 

( gm_$direct 

. 1 

' P 

. 8 

, status 

); 
check ( status ) ; 



■C Initialize the 2D GMR package. } 



gm_$f ile_create 
( 'gmflle' 
. 6 
, gm_$overwrite 



■C Create and name metafile. } 
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, gm_$l¥ 
, file_id 
, status 
): 
check ( status ) ; 

gm_$viewport_set_refresh_state 
( gm_$refresh_wait 
, status 



{ Set viewport refresh state. > 



check ( status ) 



gm_$font_family_include 

( 'ffO' 

. 3 

. gin_$pixel 

. ffid_pixel 

, status 

); 
check ( status ) ; 



{ Include pixel font family. } 



gm_$font_famlly_include 

( 'ffs' 

, 3 

, gm_$stroke 

. ffid_stroke 

. status 

): 
check ( status ) ; 

gni_$ablock_create 
( 1 

, ablock_id 
, status 

); 
check ( status ) ; 

gm_$ablock_assign_display 
( aclassl 
. ablock_id 
, status 

): 

check( status ) ; 

gm_$segment_create 
C " 

. 

, sid_text 

. status 

); 
check ( status ) : 



{ Include stroke font family. > 



•[ Create an ablock. > 



{ Ablock id = aclassl . > 



-C Create a text segment. } 



gm_$aclass 

( aclassl 
, status 
); 

check ( status ) ; 



< Add an aclass command > 



p.x 



5: 
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py 

q.x 
q.y 



= - 5; 
= + 5; 
= + 5; 



gin_$rectangle_16 
( P 

. q 

, FALSE 
, status 
); 
check ( status ); 



"C Add an unfilled rectangle. > 



p.x := + 10; 
p.y := 0; 

gm_$text_2dl6 

( P 
, 0.0 

. 'Left to Right' 
, 13 

, Status 
); 
check ( status ); 



< Add Left to Right text > 



p.x := 0: 
p.y := - 10; 

gm_$text_2dl6 

( P 

. 90.0 

, 'Top to Bottom* 
. 13 

. status 
); 
check ( status ); 



< Add Top to Bottom text. > 



p.x := - 10; 
p.y := 0; 

gm_$text_2dl6 

( P 

. 180.0 

. 'Right to Left' 
. 13 

, Status 
); 
check ( status ) ; 



{ Add Right to Left text. > 



p.x : = 
p.y : = 



0; 
10; 



gm_$text_2dl6 

( P 

, -90.0 

, 'Bottom to Top' 
, 13 

, status 
); 
check ( status ); 



i Add Bottom to Top text. > 
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gm_$segment_close 

( true 

, status 

); 
check ( status ) : 



{ Close the segment. > 



dbounds .xmin 
dbounds . ymin 
dbounds . xmax 
dbounds . ymax 



= - 50.0; 
= - 50.0; 
= + 50.0; 
= + 50.0; 



pause. low32 := second DIV 4; 
pause .highie := 0; 

text_slze := 10; 
text_size_delta := 1.0; 

< * * Illustrate different text sizes with pixel and stroke text. * * } 

FOR j := 1 TO 2 
DO BEGIN 



IF j = 1 

THEN gin_$ablock_set_font_family 

( ablock_id 

. ffid_pixel 

. status 

) 
ELSE gm_$ablock_set_font_family 

( ablock_id 

, ffid_stroke 

. status 

); 
check ( status ) ; 



< Set ablock to pixel font family. > 



■C Set ablock to stroke font family. } 



FOR i := 1 TO 20 
DO BEGIN 

IF text_size >= 10.0 

THEN text_size_delta := - ABSC text_size_delta ) 

ELSE IF text_size <= ABS( text_size_delta ) 

THEN text size delta := + ABS( text size delta ); 



text size := text size + text size delta; 



gm_$ablock_set_text_size 

( ablock_id 

, text_size 

, status 

); 
check ( status ) ; 

gm_$ d i s p 1 ay_f i 1 e_P ART 
( dbounds 
. status 

); 
check ( status ) ; 

time $¥ait 



■C Change ablock text size. > 



-C Display the file. > 



■C Admire it for a momemt . } 
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( time_$relative 
. pause 
, status 



); 

check ( status ) ; 
END; 



END; 

gm_$segment_create 
( •• 
. 

. sid_top 
, status 

); 

check ( status ) ; 



rotate .xx 
rotate. xy 
rotate .yx 
rotate .yy 



= 1.0; 
= 0,0; 
= 0.0; 
= 1.0; 



translate. X := 0; 
trans late. y := 0; 

gin_$instance_transform_2dl6 

( sid_text 

, rotate 

, translate 

, status 

); 
check ( status ) ; 

gm_$modelcmd_set_mode 

( gm_$modelcmd_replace 

, status 

); 

check ( status ) ; 



< Create top segment . > 



-C Define identity matrix. > 



< Zero translation > 



< Instance text segment into > 

< top segment. > 



< Go into replace mode . > 



< * * Illustrate different text angles with pixel and stroke text. * * > 

FOR j := 1 TO 2 
DO BEGIN 



IF j = 1 

THEN gm_$ablock_set_font_family 

( ablock_id 

, ffid_pixel 

. status 

) 
ELSE gm_$ablock_set_font_family 

( ablock_id 

, ffid_stroke 

, status 

); 
check ( status ) ; 



-C Set ablock to pixel font family. > 



{ Set ablock to stroke font > 
{ family. } 



FOR i := 1 TO 40 
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DO BEGIN 



WITH rotate 
DO BEGIN 



■C Increment the rotation matrix. } 



XX 

xy 
yy 

END; 



= cos_delta * xx + sin_delta * xy; 
= cos_cielta * yx + sin_delta * yy; 
= - yx; 
= + xx; 



gm_$instance_transform_2dl6 

( sid_text 

, rotate 

. translate 

. status 

); 
check ( status ) ; 

gm_$display_file_PART 

( dbounds 

. status 

); 
check ( status ) ; 

time_$wait 

( time_$relative 

, pause 

. status 

); 
check ( status ) ; 



< Change the angle of the instance > 
■C transform > 



{ Display the file. } 



< Admire it for a moment . > 



END; 



END; 

gm_$segment_close 

( TRUE 

, status 

); 
check ( status ) ; 

gm_$file_close 

( true 

, status 

); 
check ( status ) ; 

gm_$terminate 

( status 

); 
check ( status ) ; 



■C Close the top segment . > 



-C Close the file. > 



•C Terminate the 2D GMR package . } 



END. 
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Chapter 7 
Using Segment Characteristics 



This chapter describes the use of the primary segment in displaying a metafile. Characteristics 
that can be associated with a segment are discussed and illustrated with a program. The formats 
for coordinate data are described. 



7ol. PrimaFy Segment 

Functions : 

GM_$FILE_SET_PRIMARY_SEGMENT 
GM_$FILE_INQ_FRIMARY_SEGMENT 

The segments in the metafile have a hierarchical structure. The primary segment can be thought 
of as the root for the hierarchy of segments in the metafile. As such, the primary segment is 
assumed to be the start of the picture. When the routine GM_$DISPLAY_FILE is called, the 
primary segment is displayed. 

The first segment you create becomes the primary segment. In Figure 7-1, the primary segment is 
"scene." When you display "scene," you see the entire picture. The segments are instanced 
according to the hierarchy established by the primary segment. 



SCENE 



/ 




HOUSE TREE 




WINDOW DOOR TEXT 
Figure 7-1. Hierarchical Structure and the Primary Segment 

Using GM_$FILE_SET_PRIMARY_SEGMENT, you can specify that you want another 
segment as the primary segment. For example, with "house" as the primary segment in Figure 
7-1, you see the following upon display: house, door, eight windows, and sign. You do not see 
any trees. 

If you instance the primary segment from a segment that is not itself instanced, the primary 
segment is changed to the instancing segment. If you instance the primary segment from a 
segment that is itself instanced, the root of the instancing tree becomes the primary segment (see 
Figure 7-1). 

Use GM_$FILE_ SET _PRIMARY_ SEGMENT to change the primary segment number. Use 
GM_$FILE_INQ_PRIMARY_ SEGMENT to retrieve the number of the primary segment. 
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New Primary Segment 




Old Primary Segment 
Figure 7-2. Instancing and the Primary Segment 



7.2 o Setting Segment Characteristics 

Functions : 

GM_$SEGMENT_SET_VISIBLE 
GM_$SEGMENT_INQ_VISIBLE 
GM_$SEGMENT_SET_P ICKABLE 
GM_$SEGMENT_INQ_P ICKABLE 
GM_$SEGMENT_SET_TEMPORARY 
GM_$SEGMENT_INQ_TEMPORARY 

Segment characteristics, such as visible and pickable, are associated with a segment rather than 
being controlled by commands contained within a segment. The visible value lets you specify that 
a segment be visible or invisible when you display the file. The pickable value lets you specify 
that a segment be eligible or ineligible for selection during a search. The name of the segment, 
which you assign when you call GM_$SEGMENT_ CREATE, is also a segment characteristic. 

GM_$SEGMENT_ SET _ VISIBLE assigns a value at which the specified segment can be seen 
when you display the file. This value is used with the visible threshold and visible mask during 
display operations. This enables you to display a picture without segments of it that may clutter 
it. For example, you may want to see a picture with or without text. You can place text in a 
separate segment and then change the visible value of that segment to make it visible or invisible. 

GM_$SEGMENT_INQ_ VISIBLE returns the visible value of the specified segment. 

GM_$SEGMENT_ SET _ PICKABLE assigns a pickable value to the specified segment. This 
pickable value is used with the pick threshold and pick mask during pick operations (see Chapter 
10). GM_$SEGMENT_INQ_ PICKABLE returns the pickable value of the specified segment. 

GM_$SEGMENT_ SET _ TEMPORARY sets the current segment as temporary or permanent. 
A temporary segment is deleted when the file is closed. A temporary segment is useful for picture 
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data that you want to display but not store. This allows you to add a graphic element, such as 
enclosing boxes or a superimposed grid, which you do not want to store in the metafile. 

GM_$SEGMENT_INQ_TEMPORARY indicates whether the current segment is set to 
temporary or permanent. 



7o3o Coordinate Data Types 

Functions : 

GM_$DATA_COERCE_SET_REAL 
GM_$DATA_COERCE_INQ_REAL 

For your convenience, the 2D GMR package has multiple formats for your input of coordinate 
data. For efficiency, the 2D GMR package converts, or coerces, the coordinate data you supply 
to a different format. You need to know about 2D GMR data storage conventions because 
inappropriate mixing of formats can result in a loss of precision in stored data. However, you can 
use coordinate data types in the following ways without concern for loss of precision. 

You will not lose precision if: 

• You only supply 16-bit integer data to a segment. 

• You only supply 32-bit integer data to a segment, and store it in 32-bit segment- 
exponent format. 

If you wish to supply data in other forms or combinations, you should be aware of the 
conventions described on the paragraphs below. 

You may supply coordinate data to the modeling routines of the 2D GMR package as 16- or 
32-bit integers, or as single-precision real numbers. Different routines exist to accept data in 
these different forms. These routines are generally referred to in this document as groups. For 
example, GM_$FOLYLINE_2D[16,32,REAL] refers to a group of three routines: 

GM_$P0LYLINE_2D 1 6 
GM_$P0LYLINE_2D32 
GM_$P0LYLINE_2DREAL 

Each of these routines differs only in the data types of its coordinate parameters. Each routine 
with a data type (16, 32, or REAL) in its name indicates the type of variable or array you use to 
supply coordinate data to the 2D GMR package. 

There are two internal data storage formats: 16-bit segment-exponent and 32-bit segment- 
exponent. In either format, the following occurs: 

• All data within a segment is stored with a common binary exponent. This is stored as 
a characteristic of the segment. 

® 16-bit or 32-bit signed integers are used to store values to be multiplied by the 
common binary exponent. The choice is made by the data type specified in the name 
of the routine, for example, GM_$POLYLINE_2D16 or GM_$POLYLINE_2D32. 
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You can store 16-bit and 32-bit data in the same segment. The 16 most significant bits of 32-bit 
data correspond to the 16 bits of 16-bit data, and the 16 least significant bits simply add more 
precision. This is analogous to the extra bits of precision provided by using double-precision real 
numbers instead of single-precision real numbers. 

When you insert numbers larger than those you originally supplied, the existing values may be 
shifted. When you supply new values that are too large to be stored using the current exponent, 
the 2D GMR package changes the exponent, and shifts all existing values to conform to this new 
exponent. 

You can use GM _ $DATA_ COERCE _ SET _ REAL to indicate that coordinate data supplied in 
one form is to be coerced into another form for storage. For example, you can send data to the 
package as real variables, but store data in the file in 32-bit segment-exponent format. To 
retrieve the storage format to which real coordinates are being converted, use 
GM_$DATA_COERCE_INQ_REAL. 

Currently, you must use GM_$DATA_COERCE_SET_REAL(GM_$32,STATUS) prior to 
calling any GM_$...REAL command. The package does not currently store real data as such. 

One feature of this storage format is that you may mix integer and real data within a segment. 
For example, you can insert a coordinate value (5.5) into a segment that previously contained 
integers, without adding to the processing required to display the integer data. 

You should avoid storing data in the metafile with more precision than you need because the 
more complex calculations affect performance. You may mix data storage types within a 
segment, but not within individual commands. For example, you may find it necessary to use 
32-bit storage format for coordinate transformations to preserve precision through multiple 
coordinate transformations; but 16-bit storage format may be adequate for the primitive 
commands within these instanced segments. 

You can lose precision of original data in these cases: 

® When you coerce real data to 16-bit segment-exponent format for storage, the least 
significant bits are dropped immediately. 

® When you have stored 16-bit integer coordinate data in 16-bit segment-exponent 
format, and subsequently insert 32-bit integer or real data of absolute value larger 
than 32767. Low order bits of the original data will then be truncated. For example, 
and 1 both become 0. 

® When you have stored 16-bit or 32-bit integer coordinate data in 32-bit segment- 
exponent format, and subsequently insert real data of absolute value greater than the 
largest 32-bit signed integer. 

You will not lose precision if: 

® You only supply real data to a segment, coerce it to 32-bit segment-exponent format 
for storage, and supply data which ranges only over a factor of 128. 
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Chapter 8 
The Displaying Process 



This chapter describes the display environment and coordinate systems used with the graphics 
metafile package. Viewing routines are presented with a sample program to illustrate their use. 



8»1. Hardware and Coordinate Systems 

Functions : 

GM_$INQ_CONFIG 
GM_$INQ_BITMAF_SIZE 
GM__$C00RD_SEG_T0_BITMAP_2D 
GM_$C00RD_BITMAP_T0_SEG_2D 
GM_$COORD_P IXEL_T0_SEG_2D 
GM_$COORD_SEG_TO_P IXEL_2D 

The 2D GMR package is generally independent of the display environment. This means that you 
can run most programs that include 2D GMR routines on any DOMAIN node without modifying 
the program. The 2D GMR package rescales viewports and views according to the size of the GM 
bitmap, so that programs containing viewing routines will display all viewports for any GM 
bitmap. 

When you use the 2D GMR routines, you can easily change program execution from one display 
mode to another by changing one option in the initialization routine GM_$INIT. 

You can determine the configuration of the display device using GM_$INQ_ CONFIG. You can 
use this information to assign different attributes to a color display than to a monochromatic 
display. 

GM_$INQ_ CONFIG returns the current configuration of the display device. Possible values 
are the following: 

GM _ $BW _ 800x1024 4-bit two-board black-and-white portrait. 

GM _ $BW _ 1024x800 4-bit two-board black-and-white landscape. 

GM_$COLOR_ 1024x1024x4 4-bit two-board color configuration. 
GM_$COLOR_ 1024x1024x8 8-bit three-board color configuration. 
GM_$COLOR_ 1024x800x4 4-bit two-board color configuration. 
GM $COLOR 1024x800x8 8-bit two-board color configuration. 



GM_$INQ_ BITMAP _ SIZE returns the size of the GM bitmap in pixels, and the number of 
planes in the GM bitmap. 
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GM _ $COORD_ BITMAP _ TO _SEG__ 2D conTcrts bitmap coordinates to segment coordinates 
of the Tiewport primary segment in the current viewport. 

GM ___ $COORD__SEG__ TO ___ BITMAP _ 2D converts segment coordinates (of the viewport 
primary segment in the current viewport) to bitmap coordinates. 

GM__$COORD__PIXEL__TO__SEG__2D converts GFR bitmap coordinates used in within-GPR 
mode to segment coordinates, using a specified transformation. 

GM__$GOORD_SEG_TO_FIXEL_2D converts within-GPR segment coordinates to GPR 
bitmap coordinates, using a specified transformation. 



8.2, Display Coordinates and Mode 

This section gives an overview of display coordinates, multiple viewports, and view changes. 
Subsequent sections in this chapter describe the routines for these functions in more detail. 

When you use the 2D GMR package in borrow, direct, and main-bitmap display modes, you do 
not have to refer to pixel coordinates in a bitmap. The 2D GMR package handles all the 
transformations from world coordinates in the segment to pixels on the screen. The only 
exception to this is that you specify the size of the GM bitmap in the routine GM_$INIT. After 
that specification, the only references to coordinates on the display are in terms of fractions of the 
size of the GM bitmap. 

The term fraction-of-bitmap refers to the bitmap that was established as a result of the 
initialization command. The coordinates are from to 1 left to right and from to 1 bottom to 
top. X increases to the right; y increases up. Coordinate locations within the GM bitmap are 
expressed as fractions of the GM bitmap's size, whether it is square or nonsquare. 

Every time you display a segment in the viewport, 2D GMR calculates the transformation of the 
world coordinates to bitmap pixels for each coordinate and processes the commands in the 
metafile. The 2D GMR package also adjusts the transformations for any changes that result 
from the process. 

In addition, if you change a view by using viewing commands, by popping windows, or by 
changing the size of the DM window, the 2D GMR package recalculates all transformation 
variables in a way that is transparent to the user. All commands that adjust the size of 
viewports or that deal with locator input use window-independent coordinates. These are world 

or fractional coordinates, not device or pixel coordinates. 

You may subdivide the GM bitmap into multiple viewports, but overlapping viewports are not 
supported. As a viewport includes its border, the borders may not overlap either. When the 2D 
GMR package is initialized, one viewport is created, and it is assigned the number one. This 
viewport is defined to fill the GM bitmap; that is, it is given bounds of (0,0) through (1,1), in 
terms of fraction-of-bitmap coordinates. This viewport becomes the current viewport. Before 
creating any additional viewports, you must change the bounds of viewport 1 to make room on 
the screen for another viewport. 

To change the dimensions of the viewport, use GM __ $VIEWPORT_ SET _ BOUNDS. To 
redefine the viewport with this routine, you must provide the coordinates of any two diagonally 
opposite comers. Note that if the GM bitmap is not square, the units in the x and y directions 
are different. For example, if the bitmap ip lOOO(x) by 500(y), 0.01 means 10 pixels in the x 

direction, but only 5 pixels in the y direction. 



The Displaying Process 8-2 



An image displayed in the viewport is not physically moved on the screen as a result of a 
GM_$VIEWPORT_SET_BOUNDS command. That is, the transformation from world 
coordinates to bitmap coordinates does not change. If you make the viewport smaller, the object 
is displayed the same size on the screen. However, you will see less of it or less blank space 
around it. 

To change the size of what is displayed on the screen, you can use one of several techniques. One 
way is to use GM__$VIEWPORT_ SET _ BOUNDS, followed by GM__$DISPLAY_ SEGMENT. 
The segment will be displayed into that viewport and fill the new bounds. 

Once you have used GM_$VIEWPORT_ SET _ BOUNDS to reduce viewport 1, you can call 
GM_$V][EWPORT_ CREATE. The current viewport is the last viewport that you created or 
selected. It is the implied viewport for GM_$DISPLAY_FILE, GM_$DISPLAY___ SEGMENT, 
GM__$VIEWPORT__SET_BOUNDS, and GM_$VIEWPORT_ REFRESH. Before you go 
from one viewport to another, get the number of the current viewport so that you can return to 
it easily. GM_$VIEWPORT_INQ_ CURRENT returns the number of the current viewport. 

You may want to write an application program that does not require tracking the units on the 
display. Instead, you have the program display the whole segment and allow the user to specify 
scaling parameters by using function keys or a locator input device to move the data on the 
screen. To do this, you use the routines GM__$VIEW_ TRANSLATE, GM__$VIEW_ SCALE, 

and GM _ $VIEW _ TRANSFORM. 

GM_$VIEW_ TRANSLATE does not change the scale of the displayed data; the routine moves 
the image on the screen, translating the view in the current viewport by (x,y). X and y are 
expressed in the view transform as fractions of the GM bitmap, not fractions of the viewport. 

If the viewport fills the entire screen, you need not be concerned about the difference between 
fractions of the GM bitmap and the viewport. If you have a smaller viewport, you will have to 
get the size of the viewport. For example, in an application program, you may want to define the 
box-left button to slide the image to the left by half the viewport. You must first call 
GM_$VIEWPORT_ INQUIRE _ BOUNDS to get the bounds of the current segment. You can 
then calculate the difference between xmax and xmin for that viewport, divide by 2, and use that 
as input to the GM_$VIEW_ TRANSLATE routine. 

GM_$VIEW_ SCALE and GM_$VIEW_ TRANSFORM change the scale of what is viewed in 
the current viewport. These routines can either scale or transform the view in the current 
viewport. In both of these routines, the specified point in the GM bitmap is fixed during the 
operation. When the user moves the cursor and indicates increasing or diminishing the size of the 
image, the locator input data is returned in fraction-of-bitmap coordinates. This means that all 
points are scaled around this fixed point to allow either a scale factor or an arbitrary 2D 
transformation around this fixed point. 

With GM_$VIEW_ TRANSFORM, you use a two-dimensional transformation (2 by 2 
transformation in an array of four real values). 

You can avoid using the transformation by calling GM_$VIEW_ SCALE. The following 
example shows rescaling the screen by a factor "scale" and moving the point (point.x,point.y) to 
the center of the viewport, all in one operation. (The coordinates on the screen are expressed as 
fractions of the GM bitmap.) This example is for a 50-degree rotation: 
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i Assumes scale not equal to 1.0 > 

GM_$VIEWPORT_INQ_BOUNDS (vbounds, status): 
vceiiter_x := 0.5 * (vbounds . xmax + vbounds . xmin) : 
vcenter_y := 0.5 * (vbounds . ymax + vbounds . ymin) ; 
pointl.x := (vcenter_x - point. x * scale)/ (1.0 - scale): 
pointl.y := (vcenter_y - point. y * scale)/ (1.0 - scale): 
GM_$VIEW_SCALE (scale, polntl , status) : 

These routines allow relative view changes without tracking the view transformation or the 
displayed image. For example, the user can move the cursor to a viewport; the locator of input 
data tells the 2D GMR package what the coordinates are, in fractions of bitmap coordinates, and 
what the viewport number is. With the viewport number from the input data, the 2D GMR 
package can make that viewport the current viewport and then use the fixed point as a reference 
for scaling or transformation. 



8.3. Using Multiple Viewports 

Functions : 

GM_$VIEWPORT_CLEAR 

GM_$VIEWPORT_CREATE 

GM_$VIEWPORT_SET_BOUNDS 

GM_$VIEWPORT_INQ_BOUNDS 

GM_$VIEWPORT_SELECT 

GM_$VIEWPORT_DELETE 

GM_$VIEWPORT_INQ_CURRENT 

GM_$VIEWPORT_MOVE 

GM_$VIEWPORT_SET_BORDER_S I ZE 

GM_$VIEWPORT_INQ_BORDER_S I ZE 

When you initialize the 2D GMR package in direct, borrow, and main-bitmap modes, the package 
does the following: 

• Creates one viewport. 

® Makes the viewport fill the GM bitmap. 

• Assigns number 1 to the viewport. 

• Makes number 1 the current viewport. 

To use multiple viewports, you create additional viewports with GM_$AnEWPORT_ CREATE. 
The 2D GMR package assigns numbers to viewports as they are created. 

The current viewport is the last viewport created or selected. The current viewport is changed 
each time you call GM_$VIEWPORT_ CREATE or GM_$VlEWPORT_ SELECT. 
GM_$VIEWPORT_ CLEAR clears the current viewport. Only planes enabled by the current 
value of the plane mask are affected. 

Several routines which interact with viewports operate on the current viewport. These routines 
include GM_$VIEWPORT_SET_BOUNDS, GM_$A^WPORT_ REFRESH, 

GM_$DISPLAY_FILE, and GM_$DISPLAY_ SEGMENT. 
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GM_$VIEWPORT_INQ_ BOUNDS returns the bounds of the current viewport as fractions of 
the GM bitmap. Space outside of all viewports is empty. 

GM_^$VIEWPORT_MO"VE translates the current viewport, carrying the view with it. The 
translation is expressed in fractions of the display bitmap size. 

GM_$VIEWPORT_INQ_CURRENT returns the number of the current viewport. When 
GM_$INPUT_ EVENT _ WAIT collects locator data, it also returns the number of the viewport 
to tell what viewport you are in. 

GM_$V1EWP0RT_ DELETE deletes a viewport. Because viewports may not overlap, you 
must delete all but one viewport if a single viewport is to fill the entire GM bitmap. If you delete 
the current viewport, there is no current viewport and you must select or create a current 
viewport before calling routines that operate on the current viewport. 

GM_$VIEWPORT_ SET _BORDER_ SIZE sets the border size of the current viewport to the 
specified values, either in pixels or in fraction-of-bitmap coordinates. This routine sets sizes of 
the four edges independently, for each viewport. 

GM_$VIEWPORT_INQ_ BORDER _ SIZE returns the border size of the current viewport, 
either in pixels or in fraction-of-bitmap coordinates. 

The default border type is in pixels, and the default width is 1,1,1,1. Viewport borders are drawn 
with color value 1 for compatibility with monochrome nodes. Also for this compatibility, the 2D 
GMR package sets the color map for color value 1 to white. 

With a color node, you may want to use the viewport background color, instead of a border, to 
differentiate viewports from the overall display or the window background. Changing the color 
map to black is usually not practical because the cursor is also set to color value 1. An 
alternative is to create the viewport, set the border width to pixels, and then refresh the 
viewport. 



8.4« Segment Visibility Criteria 

Functions: 

GM_$VIS IBLE_SET_MASK 
GM_$VIS IBLE_INQ_MASK 
GM_$VIS IBLE_SET_THRESHOLD 
GM_$VISIBLE_INQ_THRESHOLD 

You can establish two criteria for segment visibility. You may use a threshold to eliminate 
segments with visible values too small. You may also use a mask to eliminate segments missing 
certain bits in their visible values. 

To assign visible values to segments, use GM_$SEGMENT_ SET _ VISIBLE (see Section 7.2). 

A segment is displayed only if it meets both the visible mask and threshold criteria. The visible 
mask criterion requires that at least one bit be "1" in both the segment's visible value and the 
visible mask. The visible threshold criterion requires that the segment's visible value be greater 
than the visible threshold. 
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One use for this pair of methods is to set the lowest bit (1) in the visible value in all segments 
containing, for example, a floor plan; the next lowest bit (2) containing data for ducting; and and 
the next bit (4) containing data for electrical systems. Higher bits can be used to give larger 
visible values to larger segments. 

With the above settings, visible masks with the following values perform in this way: 

1 displays only the floor plan 

2 displays only ducting 

5 displays the floor plan and electrical data 
7 displays all three groups of data 



If a segment does not satisfy both of the segment visibility criteria, none of that segment is 
displayed. Any segment which it instances is not checked for visibility and is not displayed. 

In borrow, direct, and main-bitmap modes, you may assign separate visible mask and threshold 
values to each viewport. Thus, different viewports can display separate parts of a data base. 
Within-GPR mode has only one visible mask and one visible threshold value. 

GM_$VISIBLE_ SET _ THRESHOLD establishes a minimum segment visible value. Segments 
with smaller visible values are not displayed. The default value is 1, in which case all segments 
of nonzero visible value satisfy the threshold criterion. 

GM_$VISIBLE_ SET _ MASK allows you to base segment visibility on individual bits within 
the visible value for each segment. If any bit is 1 in both the mask and the segment visible 
number, the segment may be visible. The default value is 16#7FFFFFFF, in which case all 

segments of nonzero visible value satisfy the mask criteria. 

GM__$VISIBLE_INQ_ THRESHOLD and GM_$VISIBLE_INQ_MASK return the current 
value of these parameters for the specified viewport. 



8.5. Displaying a File/Segment 

Functions : 

GM_$DISPLAY_FILE 

GM__$D I SFLAY__SEGMENT 

GM___$DISFLAY_SEGMENT__GPR__2D 

You can display the entire file or segment. The picture is automatically centered in the current 
viewport, with a scale calculated so that 95% of the viewport is filled in one dimension amd does 
not overflow the viewport in the other. 

A segment from one file can be displayed in one viewport. A segment from another open file can 
be displayed in another viewport. But only one segment may be displayed in any viewport, and 
it may not instance segments in other files. To display the contents of more than one segment in 
the single viewport, build a new segment including instances of the other segments. 

GM_$DISPLAY_FILE displays the entire current file in the current viewport. The primary 
segment of the file is displayed. 
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GM_$DISPLAY___ SEGMENT displays the specified segment, but not the entire file, in the 
current viewport. 

GM_$DISPLAY_ SEGMENT __GPR_ 2D is used in within-GPR mode only. It displays the 
specified segment, with the specified transformation, in the current GPR-specified bitmap (see 
Chapter 11). 



8o§« Displaying Part of a File/ Segment 

Functions : 

GM_$D ISPLAY_F ILE_FART 
GM_$D ISPLAY_SEGMENT_PART 

Only one segment may be displayed per viewport, but you can specify what part of that segment 
is displayed or change the part of that segment that is displayed. You may want to see only part 
of a graphic image you have developed. For example, you may want to see only the wheel of a 
car, not the entire body of the car that you have been modeling. 

To get part of an image in a view, you use GM__$DISPLAY_ SEGMENT _ PART or 
GM_$DISPLAY_ FILE _ PART to specify in segment coordinates the part of the segment (or 
file) you want displayed. That part of the segment (or file) is centered in the current viewport 
with a scale automatically set so that the specified part of the file is displayed as follows: One of 
the two dimensions fills the viewport, and the other dimension does not overflow the viewport. 

This allows you to look at the entire file or segment in one viewport and a smaller part of a file 
or segment in another viewport. The same file or segment can appear in different viewports (see 
Figure 4-1. 

You may want the contents of a segment to be much smaller than the viewport. This is possible 
because the 2D GMR package uses the rectangular bounds that you specify, not the current 
bounds of the coordinate data within the segment. In this way, you can override this coordinate 
data based on coordinates within the segment. 

The 2D GMR package then sets the view transformation from world coordinates of that segment 
to display pixels so that one dimension fills the current viewport 100% (not 95%). The other 
dimension is centered in the viewport and does not overflow it. This means that if the aspect 
ratio of the region you defined is different than the aspect ratio of the viewport, you will see more 
than the area you requested. It will continue to display all the way out to the edge of the 
viewport. But you are guaranteed that this entire rectangular bounded region will be viewed in 
the viewport, and one dimension or the other will fill the entire viewport. 

GM_$DISPLAY_ FILE _ PART displays part of the current file in the current viewport. 
Bounds are in segment coordinates of the primary segment. 

GM_$DISPLAY_ SEGMENT _ PART displays part of the specified segment in the current 
viewport. 
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8.7, Changing the View 

Functions: 

GM_$VIEW_TRANSLATE 
GM_$VIEW_SCALE 
GM_$VIEW_TRANSFORM 
GM_$VIEW_TRANSFORM_RESET 

Changing the view causes the picture in the current viewport to be redisplayed, with the picture 
translated or scaled. 

GM_$VIEW_ TRANSLATE translates the view in the current viewport by (x,y) in bitmap 
coordinates. The amount of translation is expressed in fractions of the size of the GM bitmap. 

GM_$VIEW_ SCALE rescales the display in the current viewport, multiplying the current view 
transformation by the specified scale factor. The point (x,y) on the screen is kept fixed during 
this rescaling. This point is expressed in bitmap coordinates, that is, fractions of the size of the 
GM bitmap. 

GM_$VIEW_TR7yMSFORM rescales the display in the current viewport, multiplying the 
current view transformation by the specified transform factor. The point (x,y) on the screen is 
kept fixed during this rescaling. This point is expressed in bitmap coordinates, that is, fractions 
of the size of the GM bitmap. 

GM_$VIEW_ TRANSFORM _RESET restores the view transformation in the current viewport 
to the value that was assigned to it at the time of the last call to 
GM_$DISPLAY_FILE[_PART] or GM_$DISPLAY_SEGMENT[_PART], adjusted for any 
GM_$VIEWPORT_MOVE calls or any changes to the GM bitmap. This allows you to 
manipulate the view experimentally and still restore it to its form at the time you displayed it. 



8.80 Refreshing the Display- 
Functions : 

GM_$D ISPLAY_REFRESH 

GM_$VIEWPORT_REFRESH 

GM_$REFRESH_SET_ENTRY 

These routines enable an application program to keep up with changes to a file or segment. The 
routines are especially useful after you have made multiple changes to a file or segment. 

GM_$DISPLAY_ REFRESH updates the display in all viewports, except viewports in the 
GM_$REFRESH_ INHIBIT refresh state (see Section 10.2). 

GM_$VIEWPORT_ REFRESH updates the display in the current viewport. This routine 
redisplays the contents of the viewport and is useful after you have made multiple changes to a 
file or segment. 

GM_$REFRESH_ SET _ ENTRY specifies a user-defined routine to be called when the display 
is refreshed as a result of using a DM refresh window command or pressing <POP>. 
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8.9. Program to Change the View 

This program opens and displays an existing file and then changes the view scale to shrink the 
viewport. (For an existing file, you may use the program in Appendix D). As viewports may not 
overlap, this makes room for a second viewport. The second viewport is created, and the file is 
displayed in it. The view scale is then changed for the second viewport. 

To illustrate the ease of switching between viewports, the first viewport it selected as the current 
viewport. This viewport is moved and made smaller to allow for the creation of a third viewport. 
The file is displayed in this third viewport, and the view scale is changed. 

PROGRAM course2; 

%NOLIST; 

%INCLUDE ' /sys/ins/base . ins . pas ' j 

%INCLUDE '/sys/lns/gmr. Ins .pas' ; 

%LIST; 

VAR 



status 


: status $t; 


name 


: name_$pname_t ; 


length 


: INTEGER: 


vpi(i2 


: INTEGER: 


vpld3 


: INTEGER: 


file_id 


: INTEGER: 


rtransl 


: gm $pointreal t: 


b 


: gni_$boundsreal_t: 



bitmap_size : gm_$pointl6_t: 
i : INTEGER: 



BEGIN 



WRITEC 'File name 
READLN ( name ) : 



): -C Input the name of the file to be displayed, 
for example, PROGRAM hotel. > 



length := LASTOF( name ) 
WHILE ( name [ length ] = 
DO length := length - 1: 

bitmap_size .X := 1024: 
bitmap_size .y := 1024: 
gm_$init 

( gm_$direct 

. stream_$stdout 

. bitmap_size 

, 8 

, status 

): 



) AND ( length > ) 



gm_$f ile_open 
( name 
. length 
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, gm_$r 
, gm_$lw 
, file_ici 
. status 
); 

gm_$ d i s p 1 ay_f i 1 e 
( status 
); 



< Now display the file. > 



rtransl.x := 0.0, 
rtransl.y := 1.0, 
gm_$view_scale 

(0.25 

, rtransl 

, status 

); 



■C Change the view scale . > 



FOR i := 1 TO 10 
DO gin_$view_scale 

(1.05 

, rtransl 

. status 

); 

rtransl .x := 0. 1; 
rtransl .y := 0.8; 
FOR i := 1 TO 10 
DO gm_$vlew_scale 

(0.92 

. rtransl 

. status 

); 



b.xmln := 0.0; 
b . ymin : = 0.6; 
b.xmax := 0.38; 
b . ymax : = 1.0; 
gm_$vie¥port_set_bounds 

( b 

, status 

); 



< Shrink the viewport . > 



b.xmin := 0.4; 
b.ymin := 0.0; 
b . xmax : = 1.0; 
b . ymax : = 0.6; 
gm_$vlewport_create 

( b 

, vpid2 

, status 

); 



< Create a second viewport. > 



gm_$display_f ile 
( status 
); 

rtransl .x := .7; 
rtransl .y := .3; 



{ Display the file in the second viewport. > 



"( Change the view scale in the second viewport. > 
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FOR i := 1 TO 10 
DO gm_$view_scale 

(1.05 

. rtransl 

, status 

); 

FOR 1 := 1 TO 3 
DO gm_$view_scale 

(0.85 

, rtransl 

. status 

); 



gin_$viewport_select 
( 1 

. status 
); 



< Switch back to the first viewport. > 



rtransl.x := 0.0: 
rtransl .y := 0.9; 
FOR i := 1 TO 10 
DO gm_$vie¥_scale 

(1.05 

, rtransl 

, status 

); 

FOR i := 1 TO 3 
DO gm_$view_scale 

( 0.9 

. rtransl 

. status 

); 



gm_$viewport_select 
( vpid2 
, status 
); 



"C Switch bade to the second viewport . > 



rtransl.x := 0.0; 
rtransl. y := -0.4; 
gm_$view_translate 

( rtransl 

. status 

); 



•C Translate the second viewport. > 



b . xmin 


= 0.4; 


b.ymin 


= 0.4; 


b . xmax 


= 1.0; 


b . ymax 


= 1.0; 


gm $viewport set bounds 


( b 


, status 


); 


b . xmin 


= 0.0; 


b . ymin 


= 0.0; 


b . xmax 


= 1.0; 



< Shrink the second viewport . > 



■C Create a third viewport. > 
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b.ymax := 0.2; 
gm_$vlewport_create 

( b 

, vpldS 

, status 

); 

gm_$display_f lie -C Display the file in the third viewport. > 
( status 
): 

gm_$viewport_inq_bounds 
( b 
. status 

); 

rtransl.x := 0.9; < Change the view scale in the third viewport. > 
rtransl .y := 0. 1; 
FOR i := 1 TO 20 
DO gm_$view_scale 

( 0.9 

, rtransl 

. status 

): 

gm_$file_close < Close the file. > 

( true 
, status 
); 

gm_$termlnate 
( status 
); 

END. 



The Displaying Process 8-12 



Chapter 9 
Developing Interactive Applications 



This chapter provides an overview of functions used for interactive editing. The routine for 
changing the editing mode is described and illustrated with a sample program. Other interactive 
functions are described in more detail in Chapter 10. 



9.1. Making Your Application Easy to Use 

To make your application program easy to use, the 2D GMR package provides the tools for 
interaction between your program and your user. The 2D GMR package has routines to establish 
editing modes, to accept input, and to refresh the display to accommodate change to an image 
and the screen. 

The routines GM_$VIEWPORT_ SET _ REFRESH _ STATE and 

GM_$VIEWPORT_INQ_REFRESH_STATE allow you to control the frequency at which the 
display in a viewport is refreshed. With these routines, you can change the metafile and have the 
package automatically update one or more viewports to incorporate these changes, without calling 
a refresh routine. One use of this feature is in a rubberbanding procedure when you are trying to 
find the right place to put a line (see Sections 9.2 and 10.2). 

The 2D GMR package has routines to control cursor activity, position, and appearance. These 
routines help establish an easy user interface. The cursor routines are described in Section 10.3). 

The routines GM_$INPUT_ ENABLE and GM_$INPUT_ DISABLE enable graphics programs 
to accept input from various input devices. The input routines can be used to synchronize 
program execution around input events. These input routines function only in direct mode and in 
borrow mode. In within-GPR mode, you must use GPR input routines (see Section 11.1.2). 

When you use input routines, you may specify whether the process is to wait until an enabled 
event occurs or to return a GM_$NO_EVENT event type if no event has occurred. To do this, 
you use the routine GM_ $INPUT_ EVENT _ WAIT. For a description of these routines, see 
Sections 10.4.1 and 10.4.2. 

Pick operations allow you to find and select segments within the metafile or commands within the 
current segment. One pick routine enables highlighting of commands. For a description of the 
pick routines, see Section 10.5). 

Editing commands allow you to insert, delete, and replace commands easily (see Section 10.10). 
The pick routines enable access to the segments and commands that you want to edit. 

The user environment of interactive applications is improved by 2D GMR routines that delete 
commands from a file, erase the contents of an entire segment, and copy segments (see Section 
10.11). 

A set of routines enables you to find out the type of command in a file. Each of these inquiring 
routines is designed to read back the contents of a command from the file and return the values 
stored in the file, in the form originally used to store that command in the file. For a description 
of these routines, see Section 10.14 and Appendix C. 
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9.2. Changing the Picture 

Functions : 

GM_$MODELCMD_SET_MODE 
GM_$MODELCMD_INQ_MODE 

You can change the appearance of a picture by changing the commands in the segment that 
defines the picture. To do this, you use editing routines to change parameters of commands in 
the segment. The editing functions in 2D GMR include replacing one command with another, 
replacing one parameter within a command with another, and rubberbanding a command to 
experiment with its placement. To perform these editing functions, use 

GM_$MODELCMD_SET_MODE and GM_$MODELCMD_INQ_MODE. These routines 
supercede GM_$REPLACE_ SET __ FLAG and GM_$REPLACE_INQ_FLAG. You may still 
use the GM_$REPLACE... routines to set and replace flags in programs that include these 
routines. New programs, however, should use the new routines. 

The new routines have the following three types and procedures; the rubberbanding mode is a 
new type without equivalence in the GM_$REPLACE... routines: 

GM _ $MODELCMD _ INSERT 

Insert the current command at the current position after the current command 
in the currently open segment. This is equivalent to 

GM_$REPLACE_SET_FLAG (false). 

GM_$MODELCMD_REPLACE 

Replace the current command at the current position in the currently open 
segment. This is equivalent to GM_$REPLACE_ SET _ FLAG (true). 

GM _ $MODELCMD _ RUBBERBAND 

Temporarily move (rubberband) the current command. The current command 
is erased, the screen is updated, and the command is redrawn. This action does 
not change the metafile. 

These editing modes change the meaning of the 2D GMR modeling routines. In insert and replace 
modes, a call to the modeling routines indicates that a command is to be respectively inserted or 
replaced at the current position in the currently open segment. In rubberbanding mode, calls to 
the modeling routines update a special internal "rubberbanding command." This command is 
not contained in any segment, but is treated as if it were contained in the currently open 
segment. In particular, the coordinates of the command are in the coordinate system of the open 
segment. 

To edit an instanced segment, you must open it. You cannot edit an instanced segment from an 
instancing segment. 

In rubberbanding mode, a call to a modeling routine causes the following three actions to occur: 
m The rubberband command is XOR'ed onto the screen. (Thus erasing it.) 

• The rubberband command is updated according to the modeling command. 

® The rubberband command is XOR'ed onto the screen. (Thus drawing it.) 

Rubberband mode and the current insert and replace modes have some important differences. 
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Rubberbanding makes no permanent change to the screen and makes no change at all to the 
metafile. Rubberbanding is simply a method by which an application program can interactively 
get information from the user by means of a pointing device. After getting the information, the 
application program must then insert or replace the command with the desired values of changes. 

The GM_$REFRESH_ UPDATE refresh state is often valuable in conjunction with replace 
mode. For more information on refresh states, see Section 10.2. 



9o3. An Interactive Program 

The following program creates one segment containing sixteen filled polyline commands. The 
user can then pick and move the commands. The program illustrates the following: 

• The modeling command GM_$P0LYLINE_2D16 is used in all three model 
command modes: gm_$modelcmd_ insert, gm_$modelcmd_ replace, and 
gm _ $modelcmd _ rubberband. 

® Partial refresh is used. When you run the program, move one of the polygons over 
another, then move it again to another location. You will see that partial refresh may 
not accurately update the viewport (see Section 10.2). 

® Command highlighting is used to show which command is picked. 

• GM_$PICK_ COMMAND returns a picked command only if the command intersects 
the pick aperture. Note that a nonzero pick aperture makes picking somewhat easier. 
A nonzero pick aperature is essential when there are horizontal or vertical lines to 
pick (see Section 10.5). 

PROGRAM star_move; 

■C The following keys are enabled and perform the following actions; 

P Toggle to pick/replace a command 

Q Quit 

^X Abort rubberbanding (command is NOT replaced) 

> 

%NOLIST: 

%INCLUDE ' /sys/ins/base . ins . pas ' ; 

%INCLUDE ' /sys/ins/error . ins . pas ' j 

%INCLUDE '/sys/ins/gmr. ins .pas' ; 

^INCLUDE Vsys/ins/pfm.ins.pas' ; 

%LISTj 

CONST 

ctrlx = CHR( 16#18 ); 
stars_x = 4; 
stars_y = 4; 

VAR 

ev_type : gm_$event_t; 
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character 


CHAR; 


bitmap_pos 


gm_$pointreal_t ; 


vie¥port_id 


INTEGER; 


segment_pos 


gm_$pointreal_t ; 


status 


status_$t; 


flush ev type 


gm_$event_t; 


flush character 


CHAR; 


f lush_bitmap_pos 


gm $pointreal t; 


flush viewport id 


INTEGER; 


flush segment pes 


gm_$pointreal_t ; 


flush status 


status_$t; 


i 


INTEGER; 


J 


INTEGER; 


Ic 


INTEGER; 


star 


gm_$point_arrayl6 t 


vertices 


INTEGER; 


closed 


BOOLEAN; 


filled 


BOOT FAN; 


last segment pos 


gm $pointreal t; 


delta 


gm_$pointl6_t; 


file_id 


INTEGER; 


Sid 


gm_$segment_id_t; 


n_instances 


INTEGER32; 


bounds 


em $boundsreal t; 



command_picked 

bitmap_size 
piclc_aperture 



BOOLEAN; 

gm_$pointl6_t := [ 1024, 1024 ] 
gm_$pointreal_t := [ 4.0, 4.0 ] 



PROCEDURE check; 

BEGIN 

IF status. all <> status_$ok 
THEN pfm_$error_trap( status ); 
END; 



BEGIN 



gm_$init 

( gm_$direct 

. 1 

, bitmap_size 

. 8 

, status 

); 
check; 



< Initialize the 2D GMR package. > 



gm_$f ile_create 
( ' stars. gmr* 
, SIZEOF( 'stars. gmr' ) 
, gm_$overwrite 
, gm_$lw 
, file id 



{ Create a 2D GMR file named 'stars. gmr.' > 
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status 



check; 



gni_$data_coerce_set_real 

( gm_$32 

, status 

); 
check; 

gm_$segment_create 
( " 
. 
, Sid 
. status 
); 

check; 



< Coerce REAL data to INTEGER32. > 



■C Create an unnamed segment. > 



star C 
star [ 
star [ 
star [ 
star [ 
star [ 
star [ 
star [ 
star C 
star [ 
closed : 
filled : 
vertices 



X 


= 


000; 


y 


= 


000; 


X 


= 


400; 


■ y 


= 


300; 


.X 


= 


000; 


■ y 


= 


300; 


x 


= 


400; 


■y 


= 


000; 


.X 


= 


200; 


■y 


= 


400; 



< Define a filled polyline. > 



TRUE; 
TRUE; 
:= 5; 



gm_$modelcmd_set_mode 

( gm_$modelcmd_insert 

, status 

); 

check; 

FOR i := 1 TO stars_x 
DO BEGIN 

FOR j := 1 TO stars_y 
DO BEGIN 

gm_$polyline_2dl6 
( vertices 
. star 
. closed 
, filled 
, status 
); 



< Set model command mode to insert. > 



< Insert polylines into the segment. > 



1 TO vertices 

k ] .y := star [ k ] .y 



check; 

FOR k := 

DO star[ k ] .y := star[ k ] .y + 600; 

END;. 
FOR k := 1 TO vertices 
DO BEGIN 

starC k 3 .X := star[ k ] .x + 600; 

starC k ] .y := start k ] .y - 600 * stars__y; 

END; 
END; 
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gm__$(iisplay_segment 

( Sid 

, status 

): 
check; 

gm_$viewport_set_refresh_state 
( gm_$refresh_partial 
. status 
); 

check; 



■C Display the segment. > 



■C Set the refresh state to partial . > 



gm_$cursor_set_active 

( TRUE 

, status 

); 
check; 



< Make the cursor active . > 



gm_$input_enable 

( gm_$key stroke 

. [ ctrlx 
. 'P' 
. 'Q' 
. 'P* 

' 'q' 
] 

, status 
); 
check; 



i Enable keys ""X, P, and Q. > 



gm_$input_enable 

( gm_$locator 

. U 

. status 

); 
check; 



< Enable locator events . > 



command_picked := FALSE; 
REPEAT 



gm_$input_event_wait 

( TRUE 

, ev_type 

, character 

. bitmap_pos 

, viewport_id 

. segment_pos 

, status 

); 
check; 

IF ev_type = gm_$locator 

THEN REPEAT 

gm_$input_event_wait 
( FALSE 

, f lush_ev_type 
, f lush_charaGter 
. f lush_bitmap_pos 



■C Wait for an event . > 



< Flush the queue . > 
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, f lush_viewport_id 

. f lush_segment_pos 

, flush_status 

); 
IF f lush_ev_type <> gm_$no_eveiit 
THEN BEGIN 



= f lush_ev_type; 
= f lush_characterj 
= f lusli_bitmap_pos: 
= f lush_viewport_id; 
= f lusli_segment_pos; 
= flush status; 



ev_type 
character 
bitmap_pos 
vlewport_id 
segment_pos 
status 
check; 
END; 
UNTIL f lush_ev_type <> gm_$locator; 

CASE ev_type OF { Do case event type . } 

gm_$keystroke : 

CASE character OF 

.p. . 

IF NOT command_picked 
THEN BEGIN 

gm_$pick_set_center < Set the pick center . } 
( segment_pos 
. status 

); 

check; 

gm_$pick_set_size -C Set the pick aperture. > 

C pick_aperture 

, status 

); 
check; 
gm_$pick_segment •{ Clear the old pick list. } 

C gm_$clear 

, Sid 

, n_instances 

, bounds 

, status 

); 
check; 
gm_$pick_segment ■( Set up pick at the top segment . } 

( gm_$setup 

, Sid 

. n_instances 

, bounds 

, status 

); 

IF status. all = status_$ok 
THEN BEGIN 

gm_$pick_command { Initialize the pick_command. > 

( gm_$start 
, status 
); 
check; 
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gm_$pick_command i Pick a command. > 

( gm_$cnext 

, status 

): 
command_picked := status. all = status_$ok; 
END; 
IF command_plcked 
THEN BEGIN 

gm_$pick_higlilight_command < Highlight the picked > 

C gm_$outline < command. > 

, 1.0 

. status 

): 
check; 

gm_$inq_polyline_2dl6 { Inquire about the > 

{ picked polyline. > 

( vertices 

, star 

. closed 

. filled 

, status 

); 
check; 
gm_$modelcmd_set_mode < Change to rubberband mode . > 

( gm_$modelcmd_rubberband 

, status 

); 
check; 
gm_$cursor_set_active < Turn off the cursor . > 

( FALSE 

. status 

); 
check; 

last_segment_pos := segment_pos; 
END; 
END 



ELSE BEGIN 



gm_$modelcmd_set_mode -C Change to replace mode. > 

( gm_$modelcmd_replace 

, status 

); 
check; 
gm_$polyline_2dl6 { Replace the polyline . } 

( vertices 

, star 

, closed 

, filled 

, status 

); 
check; 
gm_$cursor_set_active { Turn the cursor on. > 

( TRUE 

, status 

); 
check; 

command_picked := FALSE; 
END; 
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ctrlx: 
BEGIN 

command_picked := FALSE; 

gin_$modelcmci_set_mode -C Turn off rubberband mode. > 

( gm_$inodelcmd_replace 

, status 

); 
check; 
gm_$cursor_set_active i Turn the cursor on. > 

( TRUE 

, status 

); 
check; 
END; 



'q': 

EXIT; -C Quit. > 

END; 

gm_$locator : 

IF command_plcked 

THEN BEGIN 

delta. X := ROUND ( segment_pos . x - last_segment_pos .x ); 
delta.y ;= ROUND ( segment_pos .y - last_segment_pos .y ); 
last_segment_pos := segment_pos; 
FOR i := 1 TO vertices 
DO BEGIN 

starC i ] .x := star[ i ] .x + delta. x; 

starC i ] .y := star[ i ] .y + delta.y; 

END; 
gm_$polyline_2dl6 i Move XOR-rubberband . > 

( vertices 

, star 

, closed 

. filled 

, status 

); 
check; 
END 

ELSE BEGIN 

gm_$cursor_set_position( bitmap_pos, status ); 

check; 

END; 

END; 

UNTIL FALSE; 

gm $segment close -C Close the segment. > 

( TRUE ~ 
, status 

); 

check; 
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gm_$f ile_close 
( TRUE 
. status 
); 

clieclc; 



{ Close the file. } 



gm_$terminate 
( status 
); 

check: 



{ Terminate the session. > 



END. 
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Chapter 10 
Routines for Interactive Applications 



This chapter describes the following interactive functions: replacing commands, establishing a 
refresh state, controlling the cursor, using input operations and event reporting, picking 
operations, editing a metafile, and reading a metafile. Examples illustrate many of these 
functions. 



10,1. Editing Modes 



Functions : 

GM_$MODELCMD_SET_MODE 
GM_$MODELCMD_INQ_MODE 
GM_$REPLACE_SET_FLAG 
GM_$REPLACE_INQ_FLAG 

The routine GM_$MODELCMD_ SET _ MODE establishes the editing mode to replace, insert, 
or move (rubberband) a command (see Section 9.2). 

The GM_$MODELCMD... routines supercede the two replace routines described in this section. 
GM_$REPLACE_SET_FLAG and GM_$REPLACE_INQ_FLAG are still useable in 
programs that include them. The new routines are recommended for new programs. 

GM_$MODELCMD_SET_MODE (gm_$modelcmd_replace,*) puts the 2D GMR package in 
a mode in which commands are replaced (overwritten) within the file, not inserted. In the replace 
state, the current command is continually replaced. This is equivalent to 

GM_$REPLACE_SET_FLAG (true). 

In replace mode, you can only replace a command with a command of the same type. Calling a 
routine that attempts to write any other command type to the file will not affect the file and will 
reset the mode to GM _ $MODELCMD _ INSERT. 

GM_$MODELCMD_INQ_MODE tells you whether the 2D GMR package is in the (normal) 
insert, replace, or rubberband mode. GM_$MODELCMD_INQ_MODE relates to 
GM_$REPLACE_INQ_FLAG in this way: 



Mode 


Returned Flag 


Returned Status 


GM_$MODELCMD_INSERT 


False 





GM_$MODELCMD_REPLACE 


True 





GM_$MODELCMD_RUBBERBAND 


? 


Illegal value 



As the list above indicates, you can use the old GM_$REPLACE_FLAG routine for two of the 
modes, but not with rubberband mode. 
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10.2. Establishing a Refresh State 

Functions : 

GM_$VIEWPORT_SET_REFRESH_STATE 
GM_$VIEWPORT_INQ_REFRESH_STATE 

GM_$VIEWPORT_ SET _ REFRESH _ STATE allows you to control the frequency at which 
the display in a viewport is refreshed. This routine allows you to change the metafile and have 
the package automatically update one or more viewports to incorporate these changes, without 
calling a refresh routine. One use of this feature is in a rubberbanding procedure when you are 
trying to find the right place to put a line. 

GM_$VIEWPORT_SET_REFRESH_STATE allows you to specify the refresh state of the 
current viewport. GM_ $VIEWPORT_ INQ _ REFRESH _ STATE returns the value of the 
refresh state of the current viewport. These routines have the following types and procedures: 

GM_$REFRESH_INHIBIT 

Changing commands in the file does not immediately affect this viewport. In 
borrow mode, the viewport is redrawn only when you call 
GM_$VIEWPORT_REFRESH. In direct mode, the viewport is redrawn 
only when you call GM_$VIEWPORT_ REFRESH, or when the display is 
refreshed as the result of a DM command that causes the window to be 
redrawn. Thus, calling GM_$DISPLAY_REFRESH does not affect a 
viewport in this refresh state. 

GM_$REFRESH_WAIT 

(Default) Changing commands in the file does not immediately affect this 
viewport. In borrow mode, the viewport is redrawn only when you call 
GM_$VIEWPORT_REFRESH or GM_$DISPLAY_REFRESH. In direct 
mode, the viewport is redrawn only when you call 
GM_$VIEWPORT_REFRESH or GM_$DISPLAY_ REFRESH or when the 
display is refreshed as the result of a DM command that causes the window to 
be redrawn. 

GM_$REFRESH_PARTIAL 

Every time you change any command in the file, the following occurs: Inserted 
primitive commands are added, and deleted primitive commands are erased, 
but underlying data is not rewritten. This provides faster interactive drawing. 
You should, however, periodically clean up the accumulating inaccuracies by 
calling GM_$VIEWPORT_ REFRESH to redisplay the viewport. 

GM_$REFRESH_UPDATE 

Every time you change any command in the file, this viewport is completely 
corrected. 

Partial refresh has two aspects and uses in applications packages — partial refresh (erase) and 
partial refresh (draw): 

® Partial refresh (erase) is used when you call GM_$COMMAND_ DELETE or when 
you replace a command to erase the old command. The command is erased by 
redrawing it in the background color. This may partially erase other commands that 
overlap the erased command. 
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• Partial refresh (draw) means drawing a command without regard to precedence. 
Partial refresh (draw) is used when the application calls a modeling routine while in 
replace or insert mode. 

Partial refresh does not always update the viewport accurately. For completely accurate 
incremental updating, set the viewport state to GM_$REFRESH_ UPDATE. Extensive use of 
partial refresh may eventually force a call to GM_$VIEWPORT_ REFRESH. 



10.3. Controlling the Cursor 



Functions : 



gm_$cursor_ 
gm_$cursor^ 
gm_$cursor" 
gm_$cursor' 
gm_$cursor" 

GM $CURSOr' 



SET_ACTIVE 

SET_PATTERN 

SET_POSITION 

INQ_ACTIVE 

INQ_PATTERN 

"iNQ POSITION 



The cursor is a key element in an interactive program, 
control cursor activity, position and appearance. 



The 2D GMR package has routines to 



GM_$CURSOR_ SET _ ACTIVE turns the cursor on and off. Initially, the cursor is off. 

GM_$CURSOR__ SET _ PATTERN establishes a new cursor pattern (up to 16x16 pixels). The 
cursor pattern is defined as a sequence of rows of bits from top to bottom. Within the cursor 
pattern, you can specify which pixel is to be considered the cursor origin. You specify the 
number of pixels that are to be displayed to the left of, and above, the cursor position established 
by GM_$CURSOR_SET_POSITION (see Figure 10-1). 



x-off set 2 

(pixels to the 
left of the 
origin) 




y-offset 2 (lines above origin) 



origin 



Figure 10-1. Cursor Pattern and Position 



You must place a cursor pattern smaller than 16x16 in the high-order bits of the first words of 
the pattern: 
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VAR 

i A cursor pattern smaller than 16x16 starts in the high order bits, 
and starts in word 1 of the array > 

cursor_patternl : gm_$cursor_pattern_t 

:= [16#8080, 16#4100, 16#2200, 16#1400, 

16#800, 16#1400, 16#2200, 16#4100, 16#8080] : 

cursor_size : gm_$polntl6_t := [9,9]; 

cursor origin : gm $pointl6_t := [4.4]; 



gin_$cursor_set_pattern(gm_$bitmap.cursor_size. 

cursor_patternl , cursor_origin, status) ; 

GM_$CURSOR_ SET _ POSITION moves the cursor to a position that you specify as fractions 
of the size of the GM bitmap. 

GM_$CURSOR_INQ... routines return the current values of the cursor parameters. 



10o4o Using Input Operations 

The 2D GMR package includes a set of routines that enable graphics programs to accept input 
from various input devices. The input routines can be used to synchronize program execution 
around input events. These input routines function only in direct and in borrow mode. 

In within-GPR mode, you must use GPR input routines (see Chapter 11). 



10.4.1. Event Types 

Functions : 

GM_$ INPUT_ENABLE 
GM_$ INPUT_D ISABLE 

An event occurs when input is generated in a window (direct mode) or in the borrowed display 
(borrow mode). The 2D GMR package supports several classes of events, called event types. 
Programs use an input routine to select the type of event to be reported to them; this operation is 
called enabling an event type. The event types are the following: 

GM_$INPUT_ ENABLE enables a single type of input event. To enable multiple input types, 
call this procedure multiple times. No input events are enabled as a default. 

GM_$INPUT_ DISABLE disables a single type of input event. To disable multiple input types, 
call this procedure multiple times. 
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Table 10-1. Event Types 



Keystroke A keystroke event occurs when you type a keyboard character. Programs can 

select a subset of keyboard characters, called a keyset, to be recognized as 
keystroke events. In direct mode, keys that do not belong to the keyset are 
processed normally by the Display Manager. In borrow mode, keys not 
belonging to the keyset are ignored. 



Button A button event occurs when you press a button on the mouse or bitpad puck. 



Locator A locator event occurs when you move the mouse or the bitpad puck, or use 

the touchpad. 



Locator stop A locator stop event occurs when you stop moving the mouse or bitpad puck, 

or stop using the touchpad. 



Window transition event 

In direct mode, the cursor may move into and out of the window in which the 
GM bitmap resides. When the cursor leaves the window, the input routines 
report to the program an event of type GM_$LEFT_ WINDOW; when the 
cursor enters the window, the routines report an event type of 
GM $ENTERED WINDOW. 



10.4.2. Event Reporting 

Function: 

GM_$INPUT_EVENT_WAIT 

When you enable an event type, the input routines will report each event of the enabled type to 
the program, along with a cursor position. This position is in bitmap coordinates, that is, in 
fractions of the GM bitmap. 

When you call GM_$INPUT_ EVENT _ WAIT, you may specify whether the process is to wait 
until an enabled event occurs or to return a GM_$NO_EVENT event type if no event has 
occurred. The first argument of the routine controls this choice. (These alternatives are similar 
to the choice between the routines GPR_$EVENT_WAIT and 

GPR _ $COND _EVENT _ WAIT.) 

In borrow mode, events that have not been enabled are ignored. In direct mode, all events 
outside the Display Manager window in which 2D GMR is running are handled by the Display 
Manager. In addition, events that have not been enabled are passed to the Display Manager. 

If the enabled event type is keystroke or button, the input routines return an ASCII character 
from the enabled keyset. When defining a keyset for a keystroke event, consult the system insert 
files /SYS/INS/KBD.INS.PAS, /SYS/INS/KBD.INS.FTN, and /SYS/INS/KBD.INS.C. These 
files contain the definitions for the non- ASCII keyboard keys in the range 128 through 255. For a 
sample keyboard chart, see Appendix B. 

The input routines report button events as ASCII characters. "Down" transitions range from 
"a" to "d"; "up" transitions range from "A" to »D". The three mouse keys start with (a/A) on 
the left side. As with keystroke events, button events can be selectively enabled by specifying a 
button keyset. 
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Locator events report coordinates of the locator input, expressed in fraction-of-GM-bitmap 
coordinates. If the program has not enabled locator events, then at the next occurrence of an 
enabled event, the 2D GMR software reports the locator final cursor position to the program, 
along with the enabled event. 



10.5. Using Picking 

Pick operations allow you to find and select segments within the metafile or to find and select 
commands within the current picked segment. Picking may be done with or without respect to a 
pick aperture. 



10.5.1. Picking Without an Aperture 

When you perform picking without an aperture, you use only CM _$PICK_ COMMAND; and 
you may only use the options GM__$STEP, GM__$START, and GM_$END. These options to 
GM_$PICK_ COMMAND allow you to move about in the currently open segment and to 
change which command is the current command, that is, the command before which new 
modeling commands will be inserted. 



10.5.2. Picking With an Aperture 

The search for segments or commands can be limited to a specified range of coordinates. This 
range is called the pick aperture. Before starting to pick, you can define the pick aperture using 
the routines GM_ $SET _ PICK _ CENTER and GM _ $SET_ PICK _ SIZE. The coordinates 
and size used to set the pick aperture are in the coordinate system of the top-level segment in the 
viewport, that is, the coordinate system which GM_$INPUT_ EVENT _ WAIT uses to report 
locator events. The pick aperture is initialized to center (0,0) and size (0,0). 

Picking with an aperture requires two steps. 

1. Use GM_$PICK_ SEGMENT to define an instance path to the desired segment. 

2. Using this instance path, you may use GM_$PICK_ COMMAND to pick individual 
commands within the picked segment. 

Because a given segment may be instanced many times, an instance path to the segment is 
necessary to specify which instance is intended. Consider the following example. Suppose 
segment A is a stick man which is instanced twice into segment B and viewed in the viewport as 
shown in Figure 10-2: 



Routines for Interactive Applications 10-8 



/"•©N /"©©N 





Figure 10^2. Instancing and Picking 



The "X" is the pick center. Note that without specifying an instance path, that is, without 
specifying which instance is to be considered, the pick is ambiguous. It is unclear whether the left 
arm or the right arm has been selected. 

When picking with an aperture, use the following general sequence of operations: 

1. Close any open segment. (This is not always necessary, but you must do it before 
step 5. ) 

2. Call GM_$PICK_ SEGMENT ( gm_$setup, * ) to initialize segment picking. 

3. Call GM_$PICK_SET__CENTER and GM _$PICK_ SET _ SIZE to define the 
pick aperture. 

4. Call GM_$PICK_ SEGMENT ( appropriate option, for example, gm_$down, *) 

5. Determine whether a segment was picked, and if so, whether it is of interest. If a 
segment was not picked or the picked segment is not of interest, go back to step 4 or 
step 3. 

6. Open the picked segment. 

7. Call GM_$PICK_ COMMAND ( gm_$start, * ) to initialize command picking. 

8. Call GM_$PICK_ COMMAND ( gm_$cnext or gm_$step, *) 

9. Determine whether a command was picked, and if so, whether it is of interest. If a 
command was not picked or the picked command is not of interest, go back to step 8; 
or if you are at the end of the segment, close the segment and go back to step 4 or 
step 3. 

10. Edit the picked and open segment. If you want to edit interactively using a locator 
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device, then use GM_$PICK_ TRANSFORM _ POINT to convert coordinates from 
the top-level segment, that is, as reported by GM_ $INPUT_ EVENT _ WAIT, to the 
coordinate system of the open segment. 

11. Close the segment when you have completed editing. 



10c6. Setting the Pick Apcsrture 

Functions : 

GM_$PICK_SET_CENTER 
GM_$P I CK__SET_S I ZE 
GM_$P ICK_INQ_CENTER 
GM_$PICK_INQ_SIZE 

Setting the center and size of the pick aperture defines the part of coordinate space to use in 
searches. The size of the pick aperture may be large, small, or zero. 

GM_$PICK_ SET _ CENTER sets the center of the pick aperture in segment coordinates. 
GM_$PICK_INQ_ CENTER returns the center of the pick aperture. 

GM _$PICK_ SET _ SIZE sets the x and y tolerances for the pick aperture, in segment 
coordinates. GM_$PICK_INQ_SIZE returns the x and y tolerances for the pick aperture. 



10«7o Picking and Listing Segments 

Functions : 

GM_$P I CK_SEGMENT 
GM_$P I CK__INQ__L I ST 
GM_$PICK_HIGHLIGHT_SEGMENT 
GM_$PICK_TRANSFORM_POINT 

GM_$PICK_ SEGMENT looks for segments within the pick aperture. The search for segments 
follows one of eight rules shown in Table 10-2: 

If a segment is found, it becomes the current picked segment and the last segment on the list of 
picked segments. If no segment is found, the list of picked segments is unchanged. 

While a segment is in the list of picked segments, you may not delete or edit it. A picked 
segment must be open before you can pick commands in it. Therefore, if the open segment is not 
the picked segment, you must close it. You can then open the picked segment to make it the 
current segment. 

GM_$PICK_INQ_LIST returns the current list of picked segments. The first segment in the 
list is the segment in which the segment picking process was initialized. For example, assume 
that your file contains segments that instance other segments, as shown in Figure 10-3: 
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Table 10-2. Search Rules for Picking 



GM_$SETUP Make the viewport primary segment of the current viewport the start of the 
list of picked segments. The rest of the list is emptied. 

GM_$DOWN Find the first segment within the current picked segment that, when instanced, 
falls within the pick aperture. 

GM_$NEXT Find the next segment within the segment one higher in the list of picked 
segments, that falls within the pick aperture. 

GM_$UP Move up one level in the list of picked segments. 

GM_$TOP Proceed to the top segment in the list of picked segments, destroying the rest of 

the list of picked segments. 

GM_$CLEAR Clear the entire list of picked segments, allowing all segments to be edited or 
deleted. 

GM_$BOTTOM Perform GM_$DOWN repeatedly until a segment is reached for which 
GM_$DOWN finds nothing. 

GM_ $NEXTBOTTOM 

Perform GM_$BOTTOM. If nothing is found, perform GM__$NEXT, or one 
or more GM_$UP's followed by a GM_$NEXT, until a GM_$NEXT finds a 
segment. When a GM_$NEXT finds a segment, perform a GM_$BOTTOM 
from there. 



1 
/ \ 

J!* c> 

/ \ 

4 5 
/ / 
6 8 
/ 
7 



Figure 10-3. Instancing and Picking Segments 

If segment 1 is the viewport primary segment of the current viewport, then calling 
GM_$PICK_ SEGMENT with the following sequence of options will change the current picked 
segment and the list of picked segments, as indicated in Table 10-3. 

To find all lowest-level segments in the pick aperature, one at a time use the GM_$SETUP 
option, then GM_$BOTTOM, then GM_$NEXTBOTTOM until no further segments are 
found. 

You can generate a list of pickable segments directly instanced by another segment by picking 
that segment, then using GM_$DOWN, then using GM_ $NEXT repeatedly until no more 
matches are found. 
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Table lO-S. Example of Picking and Listing Segments 





New Current 






Option 


Picked Segment 


List of Picked 


Segments 


GM_$SETUP 


1 


1 




GM_$DOWN 


2 


1-2 




GM_$DOWN 


4 


1-2,4 




GM_$NEXT 


5 


1.2,5 




GM_$UP 


2 


1,2 




GM_$BOTTOM 


7 


1,2,4,6,7 




GM_$NEXTBOTTOM 


8 


1,2,5,8 




GM_$NEXTBOTTOM 


3 


1,3 




GM_$TOP 


1 


1 




GM $CT,FAR 


none 


none 





GM_$PICK_HIGHLIGHT_SEGMENT highlights the picked segment on the display. Only 
one instance of a segment is highlighted. 

GM_$PICK_ TRANSFORM _ POINT allows you to convert viewport segment coordinates to 
the segment coordinates of an instance of the picked segment. While any segment may be edited, 
GM_$INPUT_ EVENT _ WAIT still reports the locator position in viewport (that is, top level) 
segment coordinates. This presents no problem if only translations are involved. However, if 
scaling or rotation is used, particularly with multilevel instancing, then going from the viewport 
segment coordinates to the open segment coordinates is more difficult. This call facilitates that 
conversion. 



10.8. Picking a Command 

Functions : 

GM_$PICK_COMMAND 

GM_$P ICK_HIGHLIGHT_COMMAND 

Pick routines let you select a single entity from a file, either a segment or a command. As you 
edit a segment, you can use the pick routines to select the command you want to change. 

In editing a file, you may want to change some segments of it and protect others from change. 
You can do this by using pick mask and pick threshold routines to protect a basic picture while 
you change some elements in it. 

You may only edit commands within the current segment. The current segment has a current 
command. When you open or create a segment, that segment becomes the current segment, and 



Routines for Interactive Applications 



10-10 



the last command in the current segment becomes the current command. You can append new 
commands to this current command. 

The routine GM_$PICK_ COMMAND can change the current command. When the pick- 
command procedure finds a command, it becomes the current command. You can then read or 
edit that command. 

When you insert a new command into the metafile, it is placed just after the current command, 
and it becomes the current command. Thus, if you follow an insertion with a deletion, the last 
command you inserted is deleted. For a description of editing procedures, see Section 10,10. 

GM_$PICK_ COMMAND looks for commands within the current segment by following one of 
four search rules shown in Table 10-4: 



Table 10-4. Search Rules for Picking a Command 



GM $CNEXT 



GM $STEP 



GM $START 



GM $END 



(Next command) Find the next command which falls 
within the pick aperture, moving forward in the 
segment. 

(Forward one step) Find the next command in the 
segment. Independent of the pick aperture. 

Make the current command the blank space at the start 
of the segment. This allows a search to proceed from 
the start of the segment, or it allows commands to be 
inserted at the start of the segment. 

Make the final command in the segment the current command, 
This allows you to insert additional commands at the end 
of the segment. 



You may want to search for the next command within a viewport. You can use GM_$CNEXT 
to find the next command in a segment that falls within the pick aperture. The search may be in 
a segment that contains commands for several graphic images. The searching process, however, is 
for commands that fall within the pick aperture. 



Instance commands are treated like any other commands in this context, 
instanced segment, use GM_$PICK_ SEGMENT. 



To pick "into" an 



GM_$PICK_ HIGHLIGHT _ COMMAND highlights the current command on the display. 
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10.9« Controlling What is Picked 

Functions : 

GM_$PICK_SET_THRESHOLD 
GM_$P ICK_INQ_THRESHOLD 
GM_$PICK_SET_MASK 
GM_$PICK_INQ_MASK 

You can establish the criterion for picking and not picking segments in two ways: by using a 
threshold to eliminate segments with pickable values too small; or by using a mask to eliminate 
segments missing certain bits in their pickable values. 

To assign pickable values to segments, use GM_$SEGMENT_ SET __ PICKABLE (see Section 
7.2). 

A segment is picked only if it meets the pick mask and threshold criteria and the pick aperture 
criterion. The pick mask criterion requires that at least one bit be "1" in both the segment's 
pickable value and the pick mask. The pick threshold criterion requires that the segment's 
pickable value be greater than the pick threshold. 

A use for this pair of methods is to give segments containing text even pickable values and 
segments without text odd values, and to give large segments large pickable values. Then you 
can use the pick mask to make text segments nonpickable (pick mask =1), and the pick threshold 
to avoid searching for small objects. 

GM_$PICK_ SET _ THRESHOLD establishes a minimum segment pickable value. Segments 
with smaller pickable values are ignored in searches. The default value is 1, in which case all 
segments of nonzero pickable values are pickable. 

GM _$PICK_ SET _ MASK allows you to base segment pickability on individual bits within the 
pickable value for each segment. If any bit is 1 in both the mask and the segment pickable 
number, the segment is pickable. The default value is 16t^7FFFFFFF, in which case all segments 
of nonzero pickable value are pickable. 

GM__$PICK_INQ__ THRESHOLD and GM_$PICK__INQ_MASK enable you to ascertain the 
current value of these parameters. 



10.10, Editing Metafiles 

The 2D GMR package includes commands for efficient editing of files. These commands allow 
you to insert, delete, and replace commands easily. The pick routines described in this chapter 
give ready access to the segments and commands that you want to edit. 

When you open a segment, the last command in the segment becomes the current command, 
allowing new commands to be appended. You may use GM_$PICK_ COMMAND to change the 
current command. You can then insert new commands at that point in the segment, or you can 
then use the editing commands to read, delete, or replace the command. 

Using the pick and editing commands is analogous to using editing commands in a text editor. In 
editing text, you move the cursor to just after a character that you want to change. You then 
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backspace over the item you want to delete. Similarly, you use the command 
GM_$PICK_ COMMAND to make a particular command the current command. You can then 
use GM_$COMMAND_ DELETE to delete the command. Thus, picking a command and then 
calling GM_$COMMAM)_ DELETE deletes the command you just picked. 



10»llo Deleting and Copying 

The routines for deleting and copying facilitate the use of interactive applications by making it 
easy to manipulate the contents of segments and to copy files. 



10,11.1. Deleting 

Function: 

GM_$COMMAND_DELETE 
GM_$SEGMENT_ERASE 

GM_$COMMAND__ DELETE deletes the current command. After the current command is 
deleted, the previous command in the current segment becomes the current command. If the first 
command in the segment is deleted, the blank space at the start of the segment becomes the 
current command. You must then change the current command before deleting any more 
commands. 

GM_$SEGMENT_ ERASE deletes all commands in the current segment and leaves the segment 
open so that you may insert new commands. 



10.11.2. Copying 

Function: 

GM_$SEGMENT_COPY 

GM__$SEGMENT_COPY copies the entire contents of another segment into the current 
segment. 

Note the difference between GM_$SEGMENT_COPY and the GM_$INSTANCE... routines. 
GM_$SEGMENT_COPY leaves you with two copies of the segment, allowing you to modify 
the two copies separately. The GM_$INSTANCE... routines leave you with one copy of the 
segment and a reference to that segment, so that all displayed instances can be changed by 
modifying the single instanced segment. 



10.12. Program with Picking 

The program in this section illustrates the use of all the pick functions and shows the required 
order of their use. You can use this program with any metafile, for example with the metafile 
'• hotel. gm" created by the hotel program in Appendix D. 

The listing of insert files at the top of the program includes gpr.ins.pas. This file gives access to 
the DOMAIN Graphics Primitives (GPR) routines. In general, the mixing of 2D GMR and GPR 



10-13 Routines for Interactive Applications 



is not recommended unless you specify within-GPR mode with the routine GM_$INIT. Here the 
GPR routine provides the best way to release the display that 2D GMR must acquire. The GPR 
routine releases the display to allow writing output to a stream. 

In addition, the program illustrates creating two windows: one as a transcript pad for text and 
one for display of graphics. You create an extra window with pad_$create. The command 
returns a stream id which you then use as the unit parameter in GM_$INIT. 

The routine GM_$INPUT_ ENABLE provides translation for function keys to create an easy 
user interface. 

The program pick.pas illustrates the use of the various options to GM_$PICK_ SEGMENT and 
GM_$PICK_ COMMAND. The program prompts the user for a metafile pathname, creates a 
pad in which to display the metafile, then allows the user to make calls to 
GM_$PICK_ SEGMENT and GM_$PICK_ COMMAND. Status information from the calls is 
echoed in the original window. 

The following keyboard map is used: 



key 



c. 


c 


H, 


h 


0, 


o 


P, 


P 



Q, q 



Fl 




F2 




F3 




F4 




F5 




F6 




F7 




F8 




Fl 


Shifted 


F2 


shifted 


F3 


shifted 


F4 


shifted 


PROGRAM pick: 



action taken by program 

GM_$SEGMENT_CLOSE( picked_segment , * 
GM_$PICK_HIGHLIGHT_SEGMENT( picked_segment , * 
GM_$PICK_HIGHLIGHT_COMMAND( picked_command, * 
GM_$SEGMENT_OFEN ( picked sement, * 
GM_$PICK_SET_CENTER( current mouse position, * 
GM_$PICK_SET_SIZE( 4x4, * 
quit 

GM_$PICK_SEGMENT( gm_$clear, * 
GM_$PICK_SEGMENT( gm_$setup, * 
GM_$PICK_SEG^iENT( gm_$top, * 
GM_$PICK_SEGMENT( gm_$next, * 
GM_$PICK_SEGMENT( gm_$up, * 
GM_$PICK_SEGMENT( gm_$d0¥n, * 
GM_$PICK_SEGMENT( gm_$bottom. * 
GM_$PICK_SEGNENT( gm_$nextbottom, * 

GM_$PICK_COMMAND( gm_$cnext, * 
GM_$PICK_COMMAND( gm_$step, * 
GM_$PICK_COMMAND( gm_$start, * 
GM_$PICK_COMMAND( gm_$end, * 



%NOLIST; 

^INCLUDE '/sys/ins/base . ins .pas ' ; 

%INCLUDE '/sys/ins/pfm. ins .pas ' ; 

^INCLUDE '/sys/ins/pad. ins .pas' ; 

%INCLUDE ' /sys/ins/error . ins . pas ' ; 

%INCLUDE '/sys/ins/gpr. ins .pas' ; 

^INCLUDE '/sys/ins/gmr. ins. pas' ; 
%LIST; 



{ <- ! ! ! > 



CONST 



Routines for Interactive Applications 



10-14 



VAR 



cmd_cnext 


= 


CHAR( 


16#D0 ) 


cmd_step 


= 


CHAR( 


16#D1 ) 


cmd_start 


= 


CHARC 


16#D2 ) 


cmd_end 


= 


CHAR( 


16#D3 ) 


seg_clear 


_ 


CHARC 


16#C0 ) 


seg_setup 


= 


CHARC 


16#C1 ) 


seg_top 


= 


CHARC 


16#C2 ) 


seg_next 


z: 


CHARC 


16#C3 ) 


seg_up 


= 


CHARC 


16#C4 ) 


seg down 


= 


CHARC 


16#C5 ) 


seg_bottom 


= 


CHARC 


16#C6 ) 


seg_nextt>ottom 


= 


CHARC 


16#C7 ) 



< Next command Inside pick aperture > 
{ Forward one command In segment ) ; 

ignore pick aperture > 
■C Backward to before first command in 

segment ) ; ignore pick aperture > 
{ Forward to last command in segment ) 

ignore pick aperture > 



-C Next occurrence at this level inside 
pick aperture > 

< Next higher level in segment 
hierarchy > 

< Next lower level segment inside 
pick aperture > 

{ Lowest level segment inside pick 

aperture > 
{ Lowest level segment inside pick 

aperture > 



show_windo¥ 
strid 



pad_$window_desc_t ; 
stream $id t; 



name 
length 
size 
f ile_id 
Sid 



name_$pname_t ; 

INTEGER; 

gm_$pointl6_t := [ 1024. 1024 ] 

INTEGER; 

gm_$segment_id_t ; 



ev_type 

key 

bitmap_pos 

viewport_id 

segment_pos 

status 



gm_$event_t; 
CHAR; 

gm_$pointr eal_t ; 
INTEGER; 

gm_$pointreal__t ; 
status $t; 



f lush_ev_type 
f lush_key 
f lush_bitmap_pos 
f lush_viewport_id 
f lush_segment_pos 
flush status 



gm_$event_t; 
CHAR; 

gm_$pointr eal_t ; 
INTEGER; 

gm_$pointreal_t ; 
status $t; 



plck_box 
seg_id 
ninstances 
bounds 



gm_$pointreal_t; 
gm_$segment_id_t; 
INTEGER32; 
gm_$boundsreal_t ; 



search_command 
search_segment 



gm_$search_command_t , 
gm_$search_segment_t , 



pick command_name 



ARRAY [ gm_$search_command_t ] OF string 
[ 'PICK_CMD_NEXT%' 
, •PICK_CMD_STEP%' 
. 'PICK CMD START%' 
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'PICK CMD END%' 



]: 



pick_segment_name 



ARRAY [ gm_$search_segment_t ] OF string := 

[ 'PICK_SEG_CLEAR%' 

. • P ICK_SEG_SETUP% ' 

. •PICK_SEG_TOP%' 

, 'PICK_SEG_NEXT%' 

, "PICK_SEG_UP%' 

. •PICK_SEG_DOWN%' 

, 'PI CK_SEG_BOTTOM% ' 

. 'PICK SEG NEXT BOT%' 



PROCEDURE squawk 
( IN status 
j IN key 
: IN str 



) 



: UNIV status_$t 
: UNIV error_$string_t 
: UNIV error_$string_t 
IN al, a2. a3, a4, a5, a6, a7,a8, a9,alO: UNIV error_$integer32 
OPTIONS ( VARIABLE ); 



VAR 



acq_rel_cnt 
unobscured 
st 
keylen 



INTEGER; 

INTEGER: 

BOOLEAN; 

status_$t; 

INTEGER; 



BEGIN 



BEGIN 



keylen := 1; 

WHILE ( key[ keylen ] <> '%' ) AND ( keylen < SIZEOF( key ) ) 

DO keylen := keylen + 1; 

gpr_$force_release( acci_rel__cnt. st ); 

error_$print_format( status, streain_$stdout, 'I', key. keylen-1. 

str, al,a2,a3,a4, a5,a6,a7,a8, a9, alO ); 

FOR 1 := acq_rel_cnt - 1 DOWNTO 

DO unobscured := gpr_$acquire_display( st ); 

END; 



WRITEC 'File name: ' ); 
READLN ( name ) ; 



length := LASTOF( name ); 
WHILE ( name [ length ] = 
DO length := length - 1; 



) AND ( length > ) 



show_¥lndow . top 
sho¥_windo¥ . left 
show_¥lndo¥ . ¥idth 
show_window . height 



= 0; 
= 0; 
= 1023, 
= 600; 



Routines for Interactive Applications 



10--16 



pad_$create_wlnd.o¥( '', 0. paci_$ transcript, 1, show_¥indow, strid, 

status) ; 
IF status. all <> status_$olc THEN pfm_$error_trap( status ); 



pad_$set_auto_close( strid, 1, TRUE, status ): 
IF status. all <> status_$ok THEN pfm_$error_trap 

pad_$set_scale( strid, 1, 1, status ); 

IF status. all <> status_$ok THEN pfm_$error_trap 

gin_$init( gni_$direct, strld, size, 8, status ); 
IF status. all <> status_$ok THEN pfm_$error_trap 



gm_$f ile_open( name, length, gm_$wr, gm_$lw, file_id, status ) 



IF status. all <> status_$ok THEN pfm_$error_trap 

gm_$display_file( status ); 

IF status, all <> status_$olc THEN pfni_$error_trap 

gm_$cursor_set_active( TRUE, status ); 

IF status . all <> status_$o}c THEN pf m_$error_trap 



status ) ; 
status ) ; 
status ) ; 



status ) ; 
status ) ; 
status ) ; 



gm_$input__enable 

( gm_$key stroke 

. [ 'C, 'H', '0', 'P', 'Q', 'c', 'h', 'o', 'p', 'q' 

, cmd_cnext, cmd_step, cmd_start, cmd_end 

, seg_clear, seg_setup, seg_top, seg_next 

. seg_up, seg_down, seg_bottoni, seg_nextbottom 

] 
, status 
); 
IF status. all <> status_$ok THEN pfin_$error_trap( status ); 

gm_$input_enat)le( gm_$locator, [] , status ); 

IF status. all <> status_$ok THEN pfm_$error_trap( status ); 

INTEGER32( seg_id ) := ~1; 

REPEAT 

gm_$input_event_¥ait( TRUE, ev_type, key, bitmap_poS, viewport_id, 

segment_pos, status ); 
IF status. all <> status_$ok THEN pf m_$error_trap ( status ); 

IF ev_type = gin_$ locator 
THEN REPEAT 

gm_$input_event_¥ait( FALSE, f lush_ev_type, flusli_key, 

f lush_bitmap_pos, f lush__vle¥port_id, 
flush_segment_pos, flush_status ); 

IF f lush_ev_type <> gm_$no_event 
THEN BEGIN 

ev_type := f lush_ev_type: 

key := flush_key; 



bitmap_pos 
vie¥port_id 
segment_pos 
status 



= f lush_bitmap_pos; 
= f lusli_viewport_id; 
= f lush_segment_pos; 
= flush status: 
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IF status. all <> status_$oK: THEN pfin_$error_trap( status ); 
END; 

UNTIL flush_ev_type <> gm_$locatorj 

IF ev_type = gm_$locator 
THEN BEGIN 

gm_$cursor_set_positioii( bitmap_pos. status ); 

IF status. all <> status_$ok THEN pf m_$error_trap ( status ); 

END 

ELSE IF ev_type = gin_$key stroke 
THEN CASE key OF 

•C\ 'c' : 

BEGIN 

gm_$segment_close( FALSE, status ); 

squawk ( status. ' SEGMENT_CLOSE% ' . 'Segment id = %8ZLH%$', 
seg__id ) ; 

IF status. all = status_$ok 
THEN INTEGER32( seg_id ) := -1; 

END; 

•H'. 'h': 
BEGIN 

gm_$pick_highlight_segment( gm_$outline, 1.0, status ); 
gm_$pick_highlight_command( gm_$outline. 1.0, status ); 

END; 

'0' , 'o' : 
BEGIN 

gm_$segment_open( seg_id. status ); 

squawk ( status, •SEGhENT_OPEN%' , 'Segment id = %8ZLH%$', 
seg_id ) ; 

END; 

'P'. 'p* : 
BEGIN 

gm_$pick_set_center( segment_pos, status ); 

squawkC status, •PICK_SET_CENTER%' , 'Center = ( %WF, %W )%$ 
segment_pos . x. segment_pos . y ) ; 

IF status. all = 
THEN BEGIN 

pick_box.x := 4.0; 
pick_box.y := 4.0; 
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gin_$pick_set_size( pick_box, status ); 

squawkC status, 'PICK_SET_SIZE%' , 'Size = ( %WF, %WF )%$'. 
pick_box.x, pick_box.y ); 

END; 

END; 

'Q'- 'q' : 
EXIT; 

cmd_cnext, cmd_step, cmd_start. cm(i_end: 
BEGIN 

search_command := gin_$searc]i_command_t( ORD( key ) - 

ORD( cmd_cnext ) ); 

gin_$pick_command( searcli_command, status ); 

squawkC status, pick_command_name [ search_command ], '%$' ); 

IF status. all = status_$ok 

THEN gin_$pick_higlilight_command( gm_$outline. 1.0, status ); 

END; 

seg_clear, seg_setup, seg_top, seg_next, seg_up, seg_down, 

seg_bottoin, seg_nextt)ottom: 

BEGIN 

search_segment := gm_$search_segment_t( ORD( key ) - 

ORD( seg_clear ) ) ; 

gm_$pick_segmeiit( search_segment, seg_id. ninstances, bounds, 
status ) ; 

IF status. all <> status_$ok 

OR ELSE search_segment = gm_$clear 

OR ELSE search_segment = gni_$setup 

THEN squawk (status, pick_segment_name [ search_segmeiit ], '%$') 

ELSE BEGIN 

squawkC status, pick_segmeiit_name [ search_segment ], 
'SEGMENT ID = %8ZLH NINSTANCES = %8LD%$ ' , 
seg_id, ninstances ) ; 

gin_$pick_liiglilight_segment( gm_$outline, 1.0, status ); 

END 

END; 

END; 

UNTIL FALSE; 

gm_$terininate 
( status 
); 
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IF status. all <> status_$olc THEN pfm_$error_trap( status ); 
END. 



10,13. Program Techniques Locator Events and Cursor Tracking 

Processing a long queue of input events can slow the tracking of the cursor. The following 
program fragment provides a technique for disposing of the queue by reading an input event, 
taking action on that event, and then emptying the input queue of further locator data. 

This technique is especially useful for dragging and rubberbanding an image. In this type of 
operation, locator data is likely to come in faster than it can be processed, but a redraw should 
only be done at the most recent cursor position. 



GM_$ INPUT_EVENT_WAIT 
( TRUE 

ev_type 

character 

bitmap_pos 

viewport_id 

segment_pos 

status 
); 
check; 

IF ev_type = gm_$locator 



< Wait for an event . > 



< Flush the queue to make sure you have 
the most recent locator event. > 



THEN REPEAT 

GM_$INFUT_EVENT_WAIT 

( FALSE 

. f lush_ev_type 

, f lush_character 

. f lush_bitmap_pos 

, f lush_vlewport_id 

. f lush_segment_pos 

. flush_status 

): 
IF flush_ev_type <> gm_$no_event 
THEN BEGIN 

ev_type 

character 

bitmap_pos 

vlewport_id 

segment_pos 

status _ 

check; 

END; 
UNTIL flush_ev_type <> gm_$locator; 



= f lush_ev_type; 
= f lush_character; 
= f lush_bitmap_pos; 
= f lush_viewport_id; 
= f lush_segment_pos; 
= flush status; 
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10.14. Reading Commands 

Functions : 

GM_$INQ_ACLASS 

GM_$ INQ_C IRCLE_ [ 1 6 . 32 . REAL] 

GM_$ INQ_COMMAND_TYPE 

GM_$INQ_CURVE_2D [ 1 6 , 32 , REAL] 

GM_$ INQ_DRAW_RASTER_OP 

GM_$ INQ_DRAW_STYLE 

GM_$ INQ_DRAW_VAHJE 

GM_$ INQ_F ILL_BACKGROUND_VALUE 

GM_$ INQ_F ILL_PATTERN 

GM_$ INQ_F ILL_VALUE 

GM_$ INQ_FONT_FAMILY 

GM_$INQ_INSTANCE_SCALE_2D [16 , 32 , REAL] 

GM_$INQ_INSTANCE_TRANSF0RM_2D [16 . 32 . REAL] 

GM_$INQ_INSTANCE_TRANSLATE_2D [16 , 32 , REAL] 

GM_$ INQ_PLANE_MASK 

GM_$INQ_P0LYLINE_2D [16 , 32 . REAL] 

GM_$INQ_PRIMITIVE_2D [16 , 32 , REAL] 

GM_$ INQ_RECTANGLE_ [16,32, REAL] 

GM_$INQ_TAG 

GM_$INQ_TEXT_2D [ 1 6 . 32 , REAL] 

GM_$ INQ_TEXT_BACKGROUND_VALUE 

GM_$ I NQ_TEXT_S I ZE 

GM_$INQ_TEXT_VALUE 

Each modeling routine that puts a command into the file has a corresponding inquiring routine. 
Each of these inquiring routines is designed to read back the contents of a command from the file 
and return the values stored in the file, in the form originally used to store that command in the 
file. The GM_$INQ... routine has the same syntax and parameters as the routine used to insert 
the command into the file, except that some of the parameters are output parameters rather than 
input parameters. 

To inquire about a command, you must use GM_$PICK_COM]S/[AND to make that command 
the current command. Then use GM_$INQ_ COMMAND _ TYPE to determine the type of 
command and the data storage type. You can then call the appropriate GM_$INQ... routine to 
read the parameters of this particular command. 

You must read the command using an appropriate data type. That is, you must use 16-bit 
inquire routines to read data stored in 16-bit storage format. You must use 32-bit integer or real 
inquire routines to read data stored in 32-bit storage format. 

See Appendix C for an example of a program that prints out the entire contents of a metafile in a 
form you can read. 
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Chapter 11 
Using Within- GPR Mode 



This chapter explains how to extend the 2D GMR package to include GPR routines and user- 
defined primitives. This extension to the 2D GMR package is illustrated with a sample program. 



11.1. Extending the 2D GMR Package 

The 2D GMR package has four modes of display that use only 2D GMR routines and commands. 
In addition, the 2D GMR package has a mode that allows you to extend the package to use a 
bitmap of the graphics primitives (GPR) package. This mode requires the use of GPR routines 
within the 2D GMR environment. 



11.1.1. Borrow, Direct, and Main-Bitmap Modes 

In borrow, direct, and main-bitmap modes, the 2D GMR package produces graphics output in the 
GM bitmap (the screen, Display Manager window, or main-memory bitmap established when the 
2D GMR package was initialized). You can see graphics output or other processes through 
viewports, which are part or all of the GM bitmap. The view is the picture that you can see in a 
viewport. Moving or scaling a view moves or scales what you see through the viewport. 

When you initialize the 2D GMR package, the command GM_$INIT establishes a single 
viewport that fills the GM bitmap. You may want to change the size of the viewport or create 
additional viewports. 

You can divide the GM bitmap into multiple viewports. You can specify that you want parts of 
the metafile displayed and moved independently in separate viewports. 



11.1.2. Within- GPR Mode 

When you use within-GPR mode, the 2D GMR package produces graphics output in the current 
GPR bitmap. When using 2D GMR in this mode, you may use the following display routines: 

• The four routines that set and inquire about criteria for segment visibility (Section 
8.4). 

• The routine GM _ $DISPLAY_ SEGMENT _ GPR _ 2D. 

• The two routines linking attribute blocks to the display (Section 13.9.1). 

A program that uses within-GPR mode must first initialize the graphics primitives package 
before it initializes the 2D GMR package. In within-GPR mode, you retain control of the display. 
This means that you must layout viewports or other types of user interface using GPR viewing 
routines. In this mode, most of the 2D GMR viewing routines are not available. 

In within-GPR mode is an application based on the graphics primitive package. Therefore, all 
coordinates established in this mode are device-dependent and use the standard graphics 
primitives coordinates. When you call a viewing routine to display a segment in a particular part 
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of the GPR bitmap, you must specify the transformation from world coordinates (that is, 
segment coordinates) to bitmap-pixel coordinates. Two routines are available to help you make 
the conversion from world, or segment, coordinates to bitmap-pixel coordinates: 
GM_$COORD_SEG_TO_PIXEL_2D and GM_$C00RD_PIXEL_T0_SEG_2D. 

The key command for displaying in within-GPR mode is 

GM_$DISPLAY_SEGMENT_GPR_2D. You can only call this routine from within-GPR 
mode. This command causes a specified segment to be displayed with the specified 
transformation. The segment and the transformation are specified as parameters of this 
command. 

The segment is displayed into the current GPR bitmap. This bitmap is the one that was current 
at the time the 2D GMR package was initialized. For the attributes required for display, the 
current bitmap uses the attribute block that is current at the time of display. These attributes 
include the clipping window and the plane mask, which must be supplied by this GPR attribute 
block. The 2D GMR package does not control placement of graphics in within-GPR mode. The 
package may, in fact, write to the entire DM window unless you have established a clipping 
window and a plane mask. 

GM_$DISPLAY_SEGMENT_GPR_2D, unlike the display routines used in borrow, direct, 
and main-memory display routines, does not clear the display before drawing. If you want the 
display cleared, you must call GPR_$CLEAR. 

When you use within-GPR mode, you can use 2D GMR attribute commands, attribute class 
commands, and attribute blocks. The current GPR attribute block specifies the starting values of 
these attributes. If any attributes are changed as the display process performs the commands in 
the metafile, the returned state of the GPR attribute block is undefined. Because the 2D GMR 
package does not necessarily return attributes to their original state, you will probably want to 
copy a separate GPR attribute block before calling GM _ $DISPLAY_ SEGMENT _ GPR _ 2D. 

The following summarizes what routines are available and not available in within-GPR mode. 

Graphics metafile routines available in within-GPR mode: 

• Modeling routines, including editing routines. 

• Attribute routines, including GM_$ABLOCK_ASSIGN_DISPLAY. 

• Display routine GM _ $DISPLAY_ SEGMENT _ GPR _ 2D; no other display routine. 

• Segment visibility criteria routines. 
® Picking routines. 

• Output routines for creating hard copy. 

Graphics metafile routines unavailable in within-GPR mode: 

• Viewport routines and viewing routines. 

• Refresh routines. (2D GMR does not track data). 

• Color map routines. (Use GPR routines.) 
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• Cursor routines. (Use GPR routines.) 

® Input routines. (Use GPR routines.) 

® Set refresh procedure. (Use GPR routines.) 

11.2. Displaying User-Defined Primitives 

Function: 

GM_$PRIMITIVE_DISPLAY_2D 

GM_ $PRIMITIVE _ DISPLAY _ 2D assigns the specified user-defined routine to the specified 
user-defined primitive number. This causes (GM_$PRIMITrVE_2D) commands using this user- 
defined primitive number to be displayed (at display time) using this routine. 

When your routine is called during the display operation, it is passed an array of transformed 
points (in screen coordinates) and an array of untransformed parameters. Your routine must use 
only GPR primitive commands. 

The following program fragments define a user-defined primitive and the insert commands that 
use the primitive. 



< This procedure defines the operation to be performed 
when displaying . > 

PROCEDURE WIDE_LINE(IN n_points : integer; 

IN points : UNIV gm_$point_arrayl6_t; 
IN n_param : integer; 
IN param : UNIV gin_$arrayreal_t; 
OUT St : status_$t) ; 
VAR 

k : integer; 
width : integer; 

BEGIN 

width := trunc (param [1] ) ; 

gpr_$move (points [1] .x-width, points [1] .y-width, st) ; 
for K := 2 to n_points do 

gpr_$line (points [k] .x-width. points [k] .y-width, st) ; 

gpr_$move (points [1] .x-¥idth, points [1] .y+width, st) ; 
for k := 2 to n_points do 

gpr_$line (points [k] .x-width, points [k] .y+width, st) ; 

gpr_$move (points [1] .x+width, points [1] .y-width, st) ; 
for k := 2 to n_points do 

gpr_$line (points [k] .x+width, points [k] .y-width, st) ; 

gpr_$move (points [1] .x+width, points [1] .y+width, st) ; 
for k := 2 to n_points do 

gpr_$line (points [k] .x+width, points [k] .y+width, st) ; 
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END; 

■C Main program > 

VAR 

prim_ptr : gm_$primltive_ptr_t; 



•C Connect this procedure with this primitive type . > 

prlm_ptr := addr(wide_line) ; 
gm_$primitlve_display_2d(wide_llne_type.prim_ptr,st) ; 



-C Insert a command to use this primitive type . > 
gm_$primitlve_2dl6 (wide_line_type , array_count, array 1 . 1 , arrayreal , st) ; 

11.3, Program Using Within-GPR Mode 

The following program initializes GPR and then initializes the 2D GMR package with fewer 
planes. Next the program draws a grid using GPR and displays a metafile over the grid. The 
program moves the metafile on the display. Next, the program adds a user-defined primitive 
command to the file and defines a user-defined display routine. 

PROGRAM course4; 

%NOLIST; 

^INCLUDE ' /sys/ins/base . ins . pas ' ; 

%INCLUDE ' /sys/ins/t ime . ins . pas ' ; 

%INCLUDE ' /sys/ins/gpr . Ins . pas ' ; 

%INCLUDE ' /sys/ins/gmr . ins . pas ' ; 

%LIST: 



CONST 



repeats = 10; 
space = 25; 
one_second = 250000; 
opcode_try_it = 1; 



VAR 



bitmap size 


: gpr_$offset_t; 


init_bitmap_desc 


; gpr_$bitmap_desc_t 


St 


: status_$t; 


k 


: INTEGER; 


m 


, 


ml 


, 


n 


, 
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nl 

file_i(i 

sidl 

sld2 

sid3 

ptl 

pt2 

trans 1 

rotate 

rtransl 

ptarray 

array real 

pause 



INTEGER; 
INTEGER; 

gin_$segment_id_t ; 



gm_$pointl6_t; 
gm_$rotate_real2x2_t ; 
gm_$pointreal_t ; 
gni_$point_arrayl6_t ; 
ARRAY [1 . . 2 ] OF real, 
time $clock t; 



< The actual definition of t7 try_it must be in a different 

Pascal module because ADDR( t7 try_it ) is needed. > 



PROCEDURE t7 try_it 

( IN n_points 
; IN points 
; IN n_param 
; IN param 
; OUT st 
) ; EXTERN; 

VAR 



INTEGER 

UNIV gm_$point_arrayi6_t 

INTEGER 

UNIV gm_$arrayreal_t 

status $t 



K 
width 



INTEGER: 
INTEGER ; 



BEGIN 



width := TRUNC( param [ 1 ] ) 

gpr_$move 

( points [ 1 ] .X - width 
, points [ 1 ] .y ~ width 



, St 

); 
FOR k := 2 TO n_points 
DO gpr_$line 

( points [ k ] .X - width 

. points [ k ] .y - width 

, St 

); 

gpr_$move 

( points C 1 ] .X - width 
, points [ 1 ] .y + width 

, St 

); 

FOR k := 2 TO n_points 
DO gpr_$line 

( points [ k ] .X - width 

. points [ k ] .y + width 

, st 

); 
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gpr_$move 

( points [ 1 ] .X -«- width 
. points [ 1 ] .y - width 
, St 

); 

FOR k := 2 TO n_points 

DO gpr_$line 

( points [ k ] .X + width 
, points [ k ] .y - width 

, St 

); 

gpr_$move 

( points [ 1 ] .X + width 
. points [ 1 ] .y + width 
, St 

): 

FOR k := 2 TO n_points 

DO gpr_$line 

( points [ k ] .X + width 
, points C k ] .y + width 

. St 



): 



END; 



> 

BEGIN 



bitmap__size .x_size := 1024; 
bitiaap_slze .y_si2e := 1024; 

gpr_$init 

( gpr_$borrow 

, stream_$stdout 

. bitmap_size 

. 7 

. init_bitmap_desc 

, St 

): 



< Initialize GPR with 8 planes. > 



gm_$init 

( gm_$within_gpr 
. stream_$stdout 
- ptl 
. 3 
. St 

); 



{ Initialize 2D GMR with 3 planes. > 



gpr_$set_draw_value 
( 9 
, St 

); 



< Set GPR draw value to 9 . > 



ml := 0; 

FOR m := 1 TO 8 

DO BEGIN 

ml := ml + 100; 

nl := 0; 

FOR n := 1 TO 8 



i Draw a grid in the GPR plane . > 
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DO BEGIN 

nl := nl + 100; 
gpr_$move 
( ml 

. nl 
, St 

); 
gpr_$llne 
C ml+1 
, nl+1 

- St 

); 

END; 
END; 

pause . low32 .= 5 * one_second; 
pause .highie := 0; 

time_$walt 

( time_$relative 
, pause 

. St 

); 



fpr_$set_draw_value 
( 1 



< You must reset the GPR draw value } 
-C because 2D GMR will use it. > 



St 



); 



gpr_$set_plane_mask 
( C .. 2 ] 



{ Change the plane mask so use of > 

■C gpr_$clear does not destroy the grid. > 



St 



); 



gm_$f ile_create 
( 'gmfile' 
, 6 

, gm_$overwrite 
, gm_$l¥ 
, file_id 
. St 

); 



■C Create a 2D GMR file. > 



gm_$segment_create 
( 'box' 
- 3 

, sidl 
, st 
); 



{ Create segment 'box.'} 



ptl .X := 0; 
ptl.y := 0; 
pt2.x := 10; 
pt2.y := 10; 
gm_$rectangle_16 

( ptl 

. pt2 



< Add unfilled rectangle to 'box.' > 
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, 


FALSE 






, 


st 






). 






gm_ 


$segment 


close 




" ( 


TRUE 

St 






). 






gm. 


$segment 


create 




" ( 


'row' 

3 

sid2 

St 






) 







■C Close segment 'box. ' > 



■C Create segment 'row. ' > 



transl.x := 0; 
trans 1 .y := 0; 



{ Instance segment 'box' } 
-C repeated times. > 



FOR k := 1 TO repeats 
DO BEGIN 

transl.x := transl.x + space; 
gm_$lnstance_translate_2dl6 
( sidl 
, trans 1 
. St 

); 

END; 



gm_$segment_close 
( TRUE 
, st 

); 

gm_$segment_create 
C 'block' 
, 5 

, sidS 
- st 
); 

transl .x := 0; 
transl .y := 250; 



■C Close segment 'row. ' } 



< Create segment 'block.' > 



Instance segment 'row' } 
repeated times . > 



FOR k := 1 TO repeats 
DO BEGIN 

transl.x := transl.x + 1 ; 
transl. y := transl. y - space; 
gm_$instance_translate_2dl6 
( sid2 
, transl 
. st 



) 



END, 



gpr_$clear 
( 
. st 
); 



■C Clear the screen. > 
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rotate .xx 


= + 0.75; 


rotate .xy 


. 00 ; 


rotate .yx 


O.OOj 


rotate .yy 


= - 0.75; 


rtransl .x 


= + 100.00; 


rtransl .y 


= + 500.00; 


gm $display segment gpr_2d 


( sidS 


. rotate 


. rtransl 


. St 


); 


time_$wait 


( time_$relative 


. pause 


. St 


); 


gpr $clear 


( 


- St 


): 





< Display the rotated and translated } 
{ segment 'block. ' > 



■C Wait a moment. > 



< Clear the screen. } 



rtransl. X := 200.0; 
rtransl. y := 500.0; 

gm_$display_segment_gpr_2d 
( sid3 



< Display segment 'block' > 

< at a new location > 



rotate 
rtransl 

St 



); 



tlme_$wait 

( time_$relative 
, pause 
, St 

); 



-C Wait a moment. > 



ptarrayE 1 ] 

ptarrayE 1 ] 

ptarrayE 2 ] 

ptarrayE 2 ] 

ptarrayE 3 ] 

ptarray E 3 ] 



x 

■ y 

.X 

■y 

.X 

• y 




= 300 
= 100 
= 300; 
= 100 
= 400; 



arrayreal E 1 ] := 5.0; 

gm_$primitive_2dl6 
( opcode_try_it 
. 3 

, ptarray 
. 1 

. arrayreal 
. st 

); 



■C Set parameters for the primitive } 
■C command. > 



{ Add the primitive command to } 
{ segment 'block. ' > 
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5m_$primitive_display_2d 
opcode_try_it 
ADDRC t7 try_it ) 

St 



gpr". 



gm_$ 



clear 


St 



display_segment_gpr_2d 
sid3 
rotate 
rtransl 

St 



time 



gm_$ 



gm_$ 



gm $t 



$¥alt 
time_$relative 
pause 

St 



egment_close 
TRUE 

St 



ile_close 
TRUE 

St 



erminate 

St 



i Define the display routine for } 
■C the primitive command. > 



{ Clear the screen. } 



< Display segment 'block' (includes } 
{ primitive command) . > 



■C Wait a moment . } 



< Close segment 'block. ' > 



{ Close the file. > 



i Terminate the 2D GMR package . > 



END. 

Analyzing the Program 

Within-GPR mode requires you to initialize GPR before calling 2D GMR. In doing so, you retain 
control of the display. This means you must layout viewports and other parts of the interface. 
Most of the 2D GMR viewing routines are not available; you must use corresponding GPR 
routines instead. 

When a viewing routine is called to display a segment in part of the GPR bitmap, you must 
specify the transformation from world coordinates to bitmap-pixel coordinates. In within-GPR 
mode, all the coordinates are device-dependent and use the standard GPR coordinates. 

The routine GM _$DISPLAY_ SEGMENT _ GPR _ 2D is the key to the display operation. This 
routine is only available from within-GPR mode and is the only routine that has this limitation. 
This routine displays a segment that is specified as one of the parameters of the routine. The 
transformation is also specified in the routine. 

The segment is displayed in the current GPR bitmap. This is the bitmap established when GPR 
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and 2D GMR were initialized. At the time of display, the attributes in the current GPR attribute 
block are used. The clipping window and the plane mask are established by this GPR attribute 
block. The 2D GMR package may write to the entire Display Manager window unless you have 
established a clipping window and a plane mask. 

Unlike the borrow, direct, and main-memory display routines, 

GM_$DISPLAY_ SEGMENT _ GPR _ 2D does not clear the display before drawing. If you 
want the display cleared, call GPR_$CLEAR. 

In within _ GPR mode, you can use 2D GMR attribute commands, attribute class commands, and 
attribute blocks. The GPR attribute block that you establish specifies the starting values of these 
attributes. During a 2D GMR display operation, 2D GMR attribute commands may change the 
GPR attribute values. However, if you use commands that change attributes during the 2D GMR 
display operation, the final state of the initial GPR attribute block is undefined. The 2D GMR 
package does not restore the starting values. Consequently, if you are going to use any 2D GMR 
commands that may change the GPR attribute block, you may want to make a copy of the GPR 
attribute block before calling GM_$DISPLAY_SEGMENT_GPR_2D. 



11.4. Migration Steps from GPR to 2D GMR 

Moving from GPR to GMR can involve three steps: 
• Use within- GPR mode with only one segment. 

® Use within-GPR mode and store graphics data in 2D GMR. 

® Use the 2D GMR package fully with viewports and viewing. 
Using One Segment 

When you use within-GPR mode and have only one segment, the result is a simple display list 
processor. Information from a database is converted into graphics commands that are put into 
one segment. This segment is displayed, and the procedure is repeated. This first step 
demonstrates some of the characteristics of the 2D GMR package, but does not enhance 
performance. 

You can display this single segment with multiple transformations. The more you redispaly this 
segment, the more useful it is in terms of display speed. When you are through with this 
segment, you can erase it and go on to the next. 

You can also create a second or third segment, approaching the second step in the migration. 
You can use incremental redisplay in this mode when appending data: a command is put into the 
segment and written to the screen, and the process is repeated. You cannot erase any of the 
image, but you can continuously display a new segment on top of old segments. When you use 
within-GPR mode, the previous image is not deleted before drawing a new image. Unless you use 
the segment multiple times, 2D GMR in this mode does not enhance performance. 

Storing Graphics Data in 2D GMR 

At this stage, 2D GMR provides the advantage of rapid redisplay. You can redisplay an image 
multiple times at rapid display speed. In this mode you still use your exisitng GPR user 
interface. 
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A more useful approach is to store the graphics data in 2D GMR, but still use within-GPR. You 
can use all the 2D GMR modeling routines and create a collection of segments for redisplay as 
needed. You can use transformation routines to redisplay segments rapidly. In addition, the 
instance commands are all available. This allows rapid redisplay speed without rewriting an 
existing GPR user interface. 

Using the 2D GMR package 

The final step is to use the 2D GMR package completely. 
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Chapter 12 

Output 



The chapter describes the routines and external file format used in generating hard-copy output 
of graphics data. 



12.1. Printing 

Functions : 

GM_$PRINT_FILE 
GM_$PRINT_FILE_PART 

The print file routines enable you to generate files for printing on a hard-copy device. These 
routines copy part or all of a 2D GMR to a bitmap, then store that bitmap in a GMF (graphics 
map file) or in a 2D GMR vector command file. 

You can specify the size in pixels of the bitmap you want created. For a GMF, you may also 
specify the scale at which the output device (e.g., printer) is to attempt to print the bitmap. You 
may print GMFs using the Shell command PRF with the -PLOT option. You may print 2D 
GMR vector command files by writing a driver for a particular device, using the format 
information provided in the next section. 

The format for vector command files is described in this chapter. For a description of GMF 
routines, see the DOMAIN System Call Reference, Volume 1. 

GM_$FRINT_FILE converts the current metafile to the specified file for subsequent printing 
on a hard-copy device. 

GM_$FRINT_ FILE _ FART converts part of the current metafile to the specified file for 
subsequent printing on a hard-copy device. The part converted is within the physical bounds you 
specify, in terms of segment coordinates of the primary segment of the metafile. 



12.2. External File Format 

You can create 2D GMR vector command files using GM_$PRINT_... routines. The format of 
these files is described in this section. Using this format, you can write a device driver for 
printing vector command files on a hard-copy output device of your choice, for example a pen 
plotter. 

The file created looks like a sequence of 2D GMR commands as stored in a 2D GMR segment. 
The command formats and op codes are described below. All output coordinate data is (x,y) 
pairs of 16-bit integers. 
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The file or segment is flattened into a single list of commands. All coordinates are transformed 
to display coordinates in accordance with the size parameter of the GM_$PRINT_... routine 
that you used to create the vector command file. In the GM_$OUTl file, the origin of 
coordinates is the top left, not the bottom left as in the metafile. The GM_$OUTl file is scaled 
to the size parameter, using the standard 95% rule that one dimension fills 95% of the size block, 
and the other dimension does not overflow the block. 

Individual commands are not clipped to the display size; your display driver must perform this 
function itself. 

The following occurs in the translation to the vector command file: 
® All instance commands are resolved. 

® Stroke text commands are decomposed into individual primitive commands. 

® Attribute class commands are decomposed into individual attribute commands. 

® Tag commands are discarded. 

Nonvector commands, such as pixel text commands, are passed through untouched; your device 
driver may use them or throw them away. 

Format Details 

The vector command file begins with a 32-byte file header that contains the length of the 
command portion of the file (that is, everything but this header) and the size you specified when 
creating the file. 

HEADER 

bytes 0-3 : length of command portion of the file, 
in bytes (4-byte integer) 

bytes 4-5 : the x size specified when creating the file 
(2-byte integer) 

bytes 6-7 : the y size specified when creating the file 
(2-byte integer) 

bytes 8-31 : unused 

The command portion of the file starts with byte 32. It contains command op codes and data, 
interspersed. All op codes are 16-bit integers; all coordinate data is 16-bit integers. All op codes 
are aligned on 16-bit word boundaries. 

The formats of the commands (their op codes and their data) are as follows: 

COMMANDS 
END OF FILE 

bytes 0-1 : 16#0000 (op code for end-of-file) 
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TOTAL LENGTH OF COMMAND = 2 bytes 

POLYLINE 

bytes 0-1 : 16#0020 (op code for polyline) 

bytes 2-3 : number of points (2-byte integer) 

bytes 4-5 : first x-coordinate (2-byte integer) 

bytes 6-7 : first y-coordinate (2-byte integer) 

bytes 8-11, ... : additional (x.y) pairs, each a pair 
of 2-byte integers 

TOTAL LENGTH OF COMMAND = 4 * (n_points + 1) bytes 

CLOSED POLYLINE 

bytes 0-1 : 16#0021 (op code for closed polyline) 

bytes 2- . . . : same as POLYLINE 

TOTAL LENGTH OF COMMAND = 4 * (n_points + 1) bytes 

FILLED POLYLINE 

bytes 0-1 : 16#0022 (op code for filled polyline) 

bytes 2- . . . : same as POLYLINE 

TOTAL LENGTH OF COMMAND = 4 * (n_points + 1) bytes 

RECTANGLE 

bytes 0-1 : 16#0030 (op code for rectangle) 

bytes 2-3 : first x-coordinate (2-byte integer) 

bytes 4-5 : first y-coordinate (2-byte integer) 

bytes 6-7 : second x-coordinate (2-byte integer) 

bytes 8-9 : second y-coordinate (2-byte integer) 
TOTAL LENGTH OF COMMAND = 10 bytes 

FILLED RECTANGLE 

bytes 0-1 : 16#0031 (op code for filled rectangle) 
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bytes 2-9 : same as RECTANGLE 
TOTAL LENGTH OF COMMAND = 10 bytes 

CIRCLE 

bytes 0-1 : 16#0040 (op code for circle) 
bytes 2-3 : center x-coordinate (2-byte integer) 
bytes 4-5 : center y-coordinate (2-byte integer) 
bytes 6-7 : radius (2-byte integer) 
TOTAL LENGTH OF COMMAND = 8 bytes 

FILLED CIRCLE 

bytes 0-1 : 16#0041 (op code for filled circle) 

bytes 2-7 : same as CIRCLE 

TOTAL LENGTH OF COMMAND = 8 bytes 

CURVE 

bytes 0-1 : 16#0050 (op code for curve) 

bytes 2-3 : curve type (2-byte integer; 

= parametric cubic spline, 

1 = 3-pt arc) 

bytes 4-5 : number of points (2-byte integer) 

bytes 6-7 : number of parameters (2-byte integer) 

bytes 8-9 : first x-coordinate (2-byte integer) 

bytes 10-11 : first y-coordinate (2-byte integer) 

bytes 12-15. ... : additional (x,y) pairs, each a pair 
of 2-byte integers 

bytes (4*n_points + 8)-(4*n__points + 11) : first parameter 

(real) 

bytes (4*n_points + 12) ~. . . : additional parameters, 

each a real value 

TOTAL LENGTH OF COMMAND = 

8 + 4 * (n_points + n_parameters) bytes 
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USER-DEFINED PRIMITIVE 

bytes 0-1 : 16#0060 (op code for user-defined primitive) 

bytes 2-3 : user-defined primitive type 
(values assigned by user) 

bytes 4- . . . : same as CURVE 

TOTAL LENGTH OF COMMAND = 

8 + 4 * (n_points + n_parameters) bytes 

PIXEL TEXT 

bytes 0-1 : 16#0070 (op code for pixel text) 

bytes 2-3 : text location x-coordinate (2-byte integer) 

bytes 4-5 : text location y-coordinate (2-byte integer) 

bytes 6-9 : text rotation in degrees (real) 

bytes 10-11 : number of characters (2-byte integer) 

byte 12 : first character 

bytes 13-... : additional characters 

If the number of characters is odd, an unused byte 
is appended to keep subsequent commands aligned on 
16-bit word boundaries. 

TOTAL LENGTH OF COMMAND = 12 + n_characters bytes, 
plus 1 if n_characters is odd 

DRAW VALUE 

bytes 0-1 : 16#0080 (op code for draw value) 
bytes 2-5 : draw value (4-byte integer) 
TOTAL LENGTH OF COMMAND = 6 bytes 

DRAW STYLE 

bytes 0-1 : 16#0081 (op code for draw style) 

bytes 2-3 : draw style (2-byte integer; 

= solid, 

1 = dotted, 

2 = patterned) 

for solid: ignored 
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for dotted: length of solid and blank portions 

of line 
for patterned: 
bytes 4-5 : replication factor; the number of times 

each bit in the pattern is to be repeated 
(2-byte integer) 

bytes 6-7 : number of bits in the pattern 
(2-byte integer) 

bytes 8-15 : the pattern of bits; only the first n_bits 
of the bits are significant (an array of 
4 2-byte integers) 

TOTAL LENGTH OF COMMAND =16 bytes 

DRAW RASTER OP 

bytes 0-1 : 16#0082 (op code for draw raster op) 

bytes 2-3 : draw raster op (2-byte integer) 

TOTAL LENGTH OF COMMAND = 4 bytes 

PLANE MASK 

bytes 0-1 : 16#0083 (op code for plane mask) 

bytes 2-3 : plane mask; see description for FORTRAN users 
in the description of GM_$PLANE_MASK in 
Chapter 16 (2-byte integer) 

TOTAL LENGTH OF COMMAND = 4 bytes 

FILL VALUE 

bytes 0-1 : 16#0090 (op code for fill value) 
bytes 2-5 : fill value (4-byte integer) 
TOTAL LENGTH OF COMMAND = 6 bytes 

FILL BACKGROUND VALUE 

bytes 0-1 : 16#0091 (op code for fill background value) 
bytes 2-5 : fill background value (4-byte integer) 
TOTAL LENGTH OF COMMAND = 6 bytes 
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FILL PATTERN 

bytes 0-1 : 16#0092 (op code for fill pattern) 

< FORMAT : OP CODE scale size pattern > 

If fill pattern is solid (that is. no fill pattern) 
these two bytes are zero, and the other bytes are 
ignored. 

bytes 2-3 : scale; the number of times each bit in the 
pattern is to be repeated (2-byte integer) 
(Currently, always 1) 

bytes 4-5 : x size; the number of bits in each row of 
the pattern (2-byte integer) 
(Currently, always 32) 

bytes 6-7 : y size; the number of rows in the pattern 
(2-byte integer) 
(Currently, always 32) 

bytes 8-135 : the pattern of bits (32 4-byte integers; 
each represents one row of the pattern) 

TOTAL LENGTH OF COMMAND = 136 bytes 



TEXT VALUE 

bytes 0-1 : 16#00A0 (op code for text value) 
bytes 2-5 : text value (4-byte integer) 
TOTAL LENGTH OF COMMAND = 6 bytes 

TEXT BACKGROUND VALUE 

bytes 0-1 : 16#00A1 (op code for text background value) 
bytes 2-5 : text background value (4-byte integer) 
TOTAL LENGTH OF COMMAND = 6 bytes 

TEXT SIZE 

bytes 0-1 : 16#00A2 (op code for text size) 

bytes 2-3 : text size in display pixels (2-byte integer) 

TOTAL LENGTH OF COMMAND = 4 bytes 
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FONT FAMILY 

bytes 0-1 : 16#00A3 (op code for font family) 
bytes 2-3 : font family id number (2-byte integer) 
TOTAL LENGTH OF COMMAND = 4 bytes 
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Chapter 13 
Attribute Classes and Blocks 



This chapter describes the use of attribute classes and blocks and explains how to tie attribute 
blocks to attribute classes for the entire display and for individual viewports. Programming 
examples illustrate the use of attribute routines. 



ISolo Terms Used with Attributes 

Chapter 5 describes how to insert attribute commands into the metafile to affect the appearance 
of subsequent primitive commands when they are displayed. You can use these attribute 
commands to change characteristics such as text size, line style, and background. The display of 
these primitive commands is in accordance with the values you assign to the attributes. 

The 2D GMR package also has a more powerful mechanism for handling attributes: attribute 
classes. The following is an outline of the procedure for using attribute classes. The references 
direct you to sections describing the parts of the procedure. 

• Create attribute classes (aclasses) (Section 13.2). 

• Assign attributes to attribute blocks (ablocks) (Sections 13.3 through 13.5). 

• Assign attribute blocks to attribute classes for display (Section 13.9). 

A program at the end of this chapter illustrates the use of attribute classes and blocks. Before 
reading in detail, skim through this entire chapter for a sense of the relationship of the steps in 
the process. Then go back and read in detail. 

Terms Defined 

• An attribute class command in a metafile indicates that you want the attribute values 
changed to values you defined elsewhere. You define the attribute values to which the 
command corresponds either elsewhere in the file, or when the file is displayed. 

• An attribute block is a collection of attribute values. You can use an attribute block 
to assign attribute values to attribute classes when the file is displayed. 



13o2. Using Attribute Classes 

Function: 
GM_$ACLASS 

Attribute classes allow you to use attributes by changing between collections of attributes, rather 
than changing each attribute each time. This is useful, for example, when you want to display 
different layers of a printed circuit board using different attributes. You can assign each layer a 
distinct attribute class number. You can then include in the file numerous commands to switch to 
a new attribute class. 
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Attribute class commands in a segment are signals to the 2D GMR package to switch among 
collections of attributes. These collections are read from attribute blocks as the segment is being 
displayed. You use attribute block routines to define the attributes associated with each 
collection when the file is displayed (see Sections 13.3 through 13.6). 

The GM_$ACLASS routine inserts into the metafile a command indicating that the attributes 
currently associated with that attribute class are to be used when displaying subsequent primitive 
commands. For example: 

gm_$aclass (5 , status) ; 

gm_$circle_16 (center. 10,false, status) ; 

gm_$aclass (7, status) ; 

gm_$circle_16 (center, 20, false, status) ; 

The above sequence of routines inserts into the metafile four commands (use aclass 5, draw a 
circle of radius 10, use aclass 7, draw a circle of radius 20). When this sequence of commands is 
displayed, the small circle is displayed using the attributes associated with aclass 5, and the large 
circle and subsequent commands are displayed using the attributes associated with aclass 7. 

At the start of a file, the default attribute class number is 1. This default is used until another 
class is designated using the command GM_$ACLASS. 

An attribute class is a means of referring to a collection of attribute values. The particular 
attribute values are defined elsewhere. 

The procedure for assigning attributes to an attribute class is as follows. You may define 
attribute blocks and then use viewing routines to associate attribute blocks with attribute classes. 
Your input to the viewing routines is the identification of the attribute class and the attribute 
block to associate with the class. This association of attribute class and attribute block may be 
for the display as a whole or for individual viewports (see Section 13.9). 

The above procedure allows you to attach attribute classes to different sets of attributes. The 
choice of attributes depends on the type of node you are using. 

This procedure also allows the user of the application to do the following: 

• Interactively modify attributes used to display the file without affecting the contents 
of the file. 

• Assign different attributes to an attribute class in different viewports. 

If you do not assign attribute values to a particular attribute class, the default attribute values 
are used (see Table 3-1). 



13.3o Creating Attribute Blocks 

Function: 
GM__$ABLOCK_CREATE 

To associate collections of attributes with attribute class numbers, you must first build an 
attribute block. 
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The attribute values in an attribute block define a set of characteristics that affect the 
appearance of the picture. An attribute block is a data structure that holds a collection of 
attribute values in a form allowing you to modify or inquire about individual attributes. These 
attributes include draw, fill, and text values; raster op codes; and the plane mask. 

Attribute block 1 contains the default collection of attribute values to which the package is 
initialized (see Table 3-1). You can use attribute block 1 as a starting point for creating new 
attribute blocks. However, you may not modify this default attribute block 1. 

To create a collection of attributes, you first define an attribute block using the routine 
GM_$ABLOCK_ CREATE. GM_$ABLOCK_ CREATE creates an attribute block identical 
to a specified existing attribute block, such as the default (ablock 1), and assigns a new ablock 
identification number to it. You then change attribute values in it using 
GM_$ABLOCK_SET... routines. For example: 

gm_$ablock_create (1 , ablockid, status) ; 
gm_$ablock_set_(iraw_value_(ablockid, 2, status) ; 

These routines create a new ablock, which the 2D GMR package assigns the identification number 
"ablockid." This new ablock contains all of the default attribute values except for the draw 
value, which has been changed to 2 by the second routine above. 

You can then use the routine GM_ $ABLOCK_ ASSIGN _ DISPLAY (defined in Section 13.9) to 
associate this new ablock with a particular aclass. For example, to associate this ablock 
"ablockid" with aclass 5, use the following: 

gm_$abloclc_assign_(iisplay(5,ablockid, status) ; 

When commands are subsequently displayed, a command to "use aclass 5" causes this collection 
of attribute values to be applied when subsequent primitive commands are displayed. 

You can use the routine GM_$ABLOCK_ ASSIGN _ VIEWPORT (described in Section 13.9) to 
associate a single aclass with different ablocks in different viewports. 



13.4. Modifying Attribute Blocks 

Functions : 

GM_$ABLOCK_SET_DRAW_VALUE 

GM_$ABLOCK_SET_DRAW_STYLE 

GM_$ABLOCK_SET_DRAW_RASTER_OP 

GM_$ABLOCK_SET_F ILL_VALUE 

GM_$ABLOCK_SET_F ILL_PATTERN 

GM_$ABLOCK_SET_FLANE_MASK 

GM_$ABLOCK_SET_TEXT_VALUE 

GM_$ABLOCK_SET_TEXT_BACKGROUND_VALUE 

GM_$ABLOCK_SET_TEXT_S IZE 

GM_$ABLOCK_SET_FONT_FAMILY 

To change attributes in an attribute block, you use a different routine for each attribute to be 
changed, identifying the attribute block that you want to change. 
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For each attribute, there is a "no-change" value (usually -1). When an attribute class refers to 
an attribute block with this value, the previous attribute value remains unchanged. This allows 
you to define attribute blocks that keep certain values constant while you change others. In this 
way, you can preserve existing attributes across changes in the attribute class without having to 
set the attributes explicitly each time. 

A complete set of these "no-change" attribute values is stored in attribute block 0. Thus, 
assigning attribute block to an attribute class would be a null operation; that is, it would 
change no attribute values. As with attribute block 1, you may copy attribute block 0, but not 
change it. For a list of these "no-change" attribute values, see Table 13-1. 



13.5. Reading Attribute Blocks 

Functions : 

GM_$ABLOCK_INQ_DRAW_VALUE 

GM_$ABLOCK_INQ_DRAW_STYLE 

GM_$ABLOCK_INQ_DRAW_RASTER_OP 

GM_$ABLOCK_INQ_F ILL_VALUE 

GM_$ABLOCK_INQ_F ILL_PATTERN 

GM_$ABLOCK_INQ_PLANE_MASK 

GM_$ABLOCK_INQ_TEXT_VALUE 

GM_$ABLOCK_INQ_TEXT_BACKGROUND_VALUE 

GM_$ABLOCK_INQ_TEXT_SIZE 

GM_$ABLOCK_INQ_FONT_FAMILY 

The routines listed above return the current values of an individual attribute in the specified 
attribute block. 

The default attribute values are shown in Table 3-1. The "no-change" attribute values are shown 
in Table 13-1. 



13.6. Copying Attribute Blocks 

Functions : 
GM_$ABLOCK_COPY 

Once you have assigned attributes to the attribute block, you may want to copy these attributes 
to an existing attribute block. To do this, use GM_$ABLOCK_COFY. To establish a new 
attribute block identical to it, use GM_$ABLOCK_ CREATE as described previously. 



13.7. Instancing and Attributes 

Chapter 5 explains that commands that change individual attribute values affect all subsequent 
commands in that segment. The same applies to a GM_$ACLASS command: the command 
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Table 13-1. "No- Change" Attribute Values 



ATTRIBUTE 


VALUE 


Draw Style 


GM_$SAME_DRAW_STYLE 


Draw Value 


-1 


Fill Value 


-1 


Fill Background Value 


-3 


Fill Pattern 


(scale = -1) 


Text Value 


-1 


Text Background Value 


-3 


Text Size 


-1.0 


Font Family ID Number 


-1 


Plane Mask 


(change = false) 


Draw Raster Op 


-1 



changes the attribute values applied to all subsequent commands in that segment. This includes 
any other segments referenced using instance commands. When display of the segment containing 
the GM_$ACLASS command is completed, the previous attribute class is restored before the 
display of commands in the instancing segment continues. 

In other words, like attribute commands and segment transformations, attribute values are 
affected forward and downward in the hierarchy of segments and commands, but never upward. 
This allows different instancing segments to apply different attributes to a particular instanced 
segment. 



13.8. Mixing Attribute Commands and Attribute Classes 

When an attribute command is encountered, it overrides all data for that attribute in all 
attribute classes. Subsequent changes of attribute class do not affect that attribute. For 
example: 

gm_$draw_value (4, status); 
gm_$aclass (any_class, status); 

After the two commands above, the draw value will be 4 regardless of the draw value in the 
attribute block that you have assigned to the attribute class any _ class. The draw value 4 is 
effectively copied into the current definition of all attribute classes. The draw value remains in 
effect until the end of the current segment is reached. 
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13«9, Attributes and Viewing Operations 

To change attributes, you may insert individual attribute commands into a file (see Chapter 5). 
Alternatively, you can insert attribute classes into a file, as described in this chapter. You can 
define attribute blocks and apply them to attribute classes, either for the GM bitmap, or in 
individual viewports. You can also apply a particular attribute block to one or more viewports 
(see Section 13.11 for a program example). 



13.9.1. Tying Ablocks to Aclasses for the Entire GM Bitmap 

Functions : 

GM_$ABLOCK_ASS IGN_D ISPLAY 
GM_$ABLOCK_INQ_ASSIGN_DISPLAY 

You can change all attributes at once on the GM bitmap as a whole. To do this, use 
GM_$ACLASS to insert commands into the file to change the attribute class to be used. In this 
routine, you specify an attribute class identification. The command is not effective until you 
associate it with an attribute block. 

You can assign attribute blocks to attribute class numbers for display purposes using 
GM_$ABLOCK_ASSIGN_DISPLAY. Your input to the display routine is this same aclass 
identification along with the identification of the attribute block you want to use. When 
commands are being displayed, the following occurs: When an "ACLASS" command is 
encountered, the attributes of the attribute block assigned to this class are subsequently used. 

You may develop a program that creates attribute blocks and assigns them to attribute classes. 
You can use such a program to display pictures that you have already created. At the time you 
view the file, you use GM_$ABLOCK_ASSIGN_DISPLAY to associate the attribute class you 
identified with the attribute block you want used. 

GM_ $ABLOCK_ ASSIGN _ DISPLAY assigns an attribute block (by number) to an attribute 
class, for the entire display. 

GM_$ABLOCK_INQ_ASSIGN._DISPLAY returns the current attribute block number 
assigned to a particular attribute class for the display. 



13.9.2. Tying Ablocks to Aclasses for Individual Viewports 

Functions : 

GM_$ABLOCK_ASS IGN_VIEWFORT 
GM_$ABLOCK_INQ_ASSIGN_VIEWPORT 

You can change all attributes at once for individual viewports of the display. The attributes in 
each viewport may be different. To change the attributes used in a viewport, do the following: 

• Use GM_$ACLASS to insert commands into the file to specify the attribute class you 
want used. In this routine, you specify an attribute class identification. The 
command is not effective until you associate it with an attribute block. 
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# You can view the file using GM_$ABLOCK__ASSIGN_ VIEWPORT. Your input to 
the display routine is this same attribute class identification, along with the 
identification of the attribute block and the viewport. 

Note that if an attribute block is specified for a viewport, it overrides the specification of an 
attribute block for the GM bitmap. 

GM_$ABLOCK_ ASSIGN _ VIEWPORT assigns an attribute block (by number) to an attribute 
class, for the specified viewport. 

GM_$ABLOCK_INQ_ASSIGN_ VIEWPORT returns the current attribute block number 
assigned to a particular attribute class, for the specified viewport. 



IS. 9. 3. Summary of Procedures 

Use the following procedures to establish attribute blocks and assign them to the GM bitmap. 

® Use GM_$ABLOCK_ CREATE to create an attribute block equivalent to the source 
block you identify. The routine returns the attribute block identification number. 

® Change the attribute block with the calls GM_$ABLOCK_SET.... In these calls, 
you specify the value of the attribute and identify the attribute block to which it 
belongs. 

® Use GM_ $ABLOCK_ ASSIGN _ DISPLAY to assign the attribute block to a class for 
the GM bitmap. This assignment is used for all viewports until you assign an 
attribute block to a class for a particular viewport using 
GM_ $ABLOCK_ASSIGN_ VIEWPORT. 

® You may subsequently change attribute values in the assigned attribute blocks. When 
you next display the picture, the result is the following: the new attribute values 
assigned to this attribute block are used whenever an attribute class command 
associated with the attribute block is encountered. 



13.10. Summary 

The 2D GMR package provides three techniques for modifying attributes. The first technique 
assigns individual attribute values within a file. 

® Change one attribute at a time within the file. To do this, put commands into the 
file to change individual attributes. 

The next two techniques associate attributes with attribute classes only when the file is displayed. 
Neither the attribute values nor the class assignment is stored in the file. 

® Change all attributes at once on the display as a whole. To do this, use 
GM_$ACLASS to put commands into the file to specify the attribute class you want 
used. Then while viewing the file, change the collection of attributes assigned to 
attribute classes. To make this change, use GM_ $ABLOCK_ ASSIGN _ DISPLAY, 
as described in Section 13.9. 
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Change all attributes at once for individual viewports of the display. The attributes in 
each viewport may be different. To do this, use GM_$ACLASS to put commands 
into a file to specify the attribute class. Then while viewing the file, change the 
collection of attributes assigned to attribute classes for individual viewports. To make 
this change, use GM_$ABLOCK_ASSIGN_ VIEWPORT, as described in Section 
13.9. 



13.11. Program with Attribute Classes and Blocks 

The following program creates a hierarchy of segments including instance commands. It displays 
the file in three viewports; adds attribute class commands to the file; assigns attribute blocks to 
attribute classes; displays the segments; closes the file; and terminates the package. 



PROGRAM courses; 

%NOLIST; 

%INCLUDE '/sys/ins/base.ins.pas' ; 

%INCLUDE '/sys/ins/time.lns.pas' ; 

%INCLUDE ' /sys/ins/gmr . ins . pas ' j 

%LIST; 

CONST 



aclassidl 


= 1; 


aclassld2 


= 2; 


vpidl 


= 1; 


one second 


= 250000; 



< Default aclass > 
i Initial viewport > 



VAR 



bitmap_size 


: gin_$poiEtl6_t; 


status 


: status_$t; 


b 


: gm_$bouEdsreal_t; 


vpid2 


, 


vpldS 


: INTEGER; 


file_id 


: INTEGER; 


sidl 


^ 


sid2 


, 


sid3 


: gm_$segment_id_t; 


ablockidl 


, 


ablockid2 


^ 


ablockidS 


: INTEGER; 


ablockid4 


_, 


ablockidS 


^ 


ablockide 


: INTEGER; 


ptl 




pt2 


: gm_$pointl6 t; 


pattern 


: gm_$dra¥_pattern_t 


pause 


: time_$clock_t; 
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BEGIN 



bltmap_size .X := 1024; 
bitmap_size .y := 1024; 

gni_$init < Initialize the 2D GMR package. > 

( gm_$borrow 
, stream_$stdout 
. bitmap_size 
, 8 
. status 

); 

b.xmin := 0.00; 
b.ymin := 0.00; 
b . xmax : = 0.49; 
b . ymax : = 0.49; 
gin_$vie¥port_set_bounds < Create viewport 1 . > 

( b 

. status 

); 

b.xmin := 0.51; 
b.ymin := 0.00; 
b . xmax : = 1 . 00 ; 
b.ymax := 0.49; 
gm_$vie¥port_create •[ Create viewport 2. > 

( b 

. vpid2 

, status 

); 

b.xmin := 0.00; 
b.ymin := 0.51; 
b . xmax : = 1 . 00 ; 
b . ymax : = 1 . 00 ; 
gm_$vie¥port_create < Create viewport 3. > 

( b 

, vpidS 

, status 

); 

gm_$f ile_create < Create and name a metafile. > 

( 'gmfile' 
. 6 

, gm_$overwrite 
, gm_$l¥ 
, file_id 
. status 
); 

gm_$segment_create < Create segment 'bottom. ' > 

( 'bottom* 
, 6 

, sidl 
. status 
); 

ptl .X := 0; 
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ptl .y := 30, 
pt.2.x := 10, 
pt2.y := 40; 
gm_$rectangle_16 

( ptl 

, pt2 

. FALSE 

, status 

); 

gm_$ dr aw_s t y 1 e 
( gm_$soli(i 
. 

. pattern 
, 

. status 
); 



< Add a rectangle to segment 'bottom. * > 



■C Change the draw style to solid. > 



ptl.x := 20; 
pt2.x := 30; 
gm_$rectangle_16 

( ptl 

. pt2 

, FALSE 

, status 

); 

gm_$segment_close 
( TRUE 
. status 

); 

gm_$segment_create 
( 'top' 
. 3 

. sid2 
, status 
); 



■C Add a rectangle to segment 'bottom. ' > 



{ Close segment 'bottom. ' > 



■C Create segment 'top.'. > 



< Add a rectangle to segment 'top.' > 



ptl .X := 0; 
ptl .y := 0; 
pt2.x := 10; 
pt2.y := 10; 
gm_$rectangle_16 

( ptl 

. pt2 

. FALSE 

. Status 

); 

gm_$instance_translate_2dl6 < Instance segment 'bottom' into segment 'top.' > 
( sidl 
, ptl 
. status 
); 



ptl.x := 20; 
pt2.x := 30; 
gm $rectangle_16 



{ Add a rectangle to segment 'top.' } 
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( ptl 

. pt2 
. FALSE 
. status 
); 
gm_$segment_close 
( TRUE 
, status 
); 

gm_$display_file 
( status 
); 

gm_$viewport_select 
( vpi<12 
, status 
); 



{ Close segment 'top.' } 



{ Display the file in viewport 3. > 



< Select viewport 2. > 



gm_$display_file 
( status 
); 

gm_$viewport_select 
( vpidl 
. status 
); 

gm_$display_f ile 
( status 

); 



< Display the file in viewport 2. } 



< Select viewport 1 . } 



< Display file in viewport 1> 



pause. low32 := 5 * one_second; 
pause. highie := 0; 
time_$wait 

( time_$relative 

. pause 

. status 

); 



gm_$ablock_create 
( 1 

, ablockidl 
, status 
); 



< Create ablockidl . > 



gm_$ablock_set_draw_style { Give ablockidl the dotted line style > 
( ablockidl < with repetition factor = 5. > 

. gin_$dotted 
, 5 

. pattern 
, 

, Status 
); 

gm_$ablock_assign_viewport < Assign ablockidl to aclassidl in viewport 1 . > 
( aclassidl 
, vpidl 
, ablockidl 
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, status 
); 

gm_$ablock_create { Create ablockid2. } 

( 1 

, ablockid2 
. status 
); 

gm_$ablock_set_draw_style { Give ablockid2 the dotted line style > 
( ablockid2 < with repetition factor = 10. } 

. gin_$dotted 
. 10 

. pattern 
, 

. status 
); 

gm_$ablock_assign_viewport { Assign ablockidl to aclassid2 in viewport 2. > 
( aclassidl 
, vpid2 
, ablockid2 
. status 
); 

gm_$ablock_create < Create ablockidS . > 

( 1 

, ablockidS 
, status 
); 

gm_$ablock_set_draw_style -C Give ablockidS the dotted line style . > 
( ablockldS < with repetition factor = 20 } 

, gm_$dotted 
. 20 

, pattern 
, 

. status 
); 

gm_$ablock_assign_viewport < Assign ablockidS to aclassidl in viewport S. > 
( aclassidl 
. vpidS 
. ablockidS 
. status 
); 

gm_$display_refresh -C Refresh display to see the effects of > 
( status -C the attribute blocks . > 

); 

time_$wait 

( time_$relative 
. pause 
. status 
); 

gm_$segment_create { Create segment 'new. ' . > 
( 'new' 
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3 

sid3 

status 



); 



ptl.x := 0; 
ptl.y := 0; 
pt2.x := 10; 
pt2.y := 10; 
gm_$rectangle_16 

( ptl 

. pt2 

. FALSE 

, status 

); 

gm $aclass 

( aclassid2 
^ status 

); 



< Add a rectangle to segment 'new. ' > 



< Add an aclass command to segment 'new. ' > 



ptl .X := 20; 
pt2.x := 30; 
gm_$rectangle_16 

( ptl 

. pt2 

, FALSE 

. status 

); 



{ Add a rectangle to segment 'new. ' > 



gm_$segment_close 
( TRUE 
. status 
); 



< Close segment 'new. ' > 



gm_$ablock_create 
( 1 

, ablockid4 
, status 
); 



{ Create ablockid4. > 



gm_$ablock_set_dra¥_style < Give ablockid4 the dotted line style > 
( ablockid4 { with repetition factor = 30. > 

gm_$dotted 
30 

pattern 


status 
); 

gm_$ablock_assign_viewport { Assign ablockid4 to aclassid2 in viewport 1 . > 
( aclassid2 
, vpidl 
. ablockid4 
. status 
); 



gm_$ablock_create 
( 1 



< Create ablockidS. > 
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, ablockidS 
, status 
): 

gm_$ablock_set_draw_style 
( ablockidS 
. gm_$dotted 
. 40 

. pattern 
. 

, status 
); 



■C Give ablockidS the dotted line style > 
■C with repetition factor = 40. > 



gm_$ablock_assign_viewport 
( aclassid2 
. vpid2 
. ablockidS 
, status 
): 



■C Assign ablockidS to aclassid2 in viewport 2. > 



gm_$ablock_create 
( 1 

, ablockidS 
, status 
); 

gin_$ablock_set_draw_style 
( ablockidS 
. gm_$dotted 
, 50 

. pattern 
, 

. status 
); 



< Create ablockidS . > 



< Give ablockidS the dotted line style > 

< with repetition factor = SO. > 



gm_$ablock_assign_viewport 
( aclassid2 
, vpidS 
, ablockidS 
. status 
); 



< Assign ablockidS to aclassid2 in viewport 3. > 



gm_$display_segment 
( sid3 
, status 
): 

gm_$viewport_s elect 
( vpid2 
, status 
); 

gm_$display_segment 
( sidS 
, status 
); 

gm_$viewport_select 
( vpid3 



< Display segment 'new* in viewport 1. > 



{ Select viewport 2. > 



< Display segment 'new* in viewport 2. > 



< Select viewport 3. > 
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, status 
); 

gm_$display_segment 
( sidS 
, status 
); 



< Display segment 'new' in viewport 3. > 



time_$wait 

( time_$relative 
. pause 
, status 
); 



gm_$file_close 
( TRUE 
. status 
); 

gm_$terininate 
( status 
); 



■C Close the file. > 



■( Terminate the 2D GMR package . > 



END 
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Chapter 14 
Advanced Display Techniques 



This chapter describes advanced display techniques including using color as well as viewport 
border and background. Programming examples illustrate these techniques. 



14ol» Using the Color Map 

Graphics programs use a color map to specify color and intensity (gray-scale) values. A program 
can redefine the color map to assign colors to pixel values. (On a monochromatic node, you can 
only switch the definitions of black and white). To assign different colors to lines or other 
graphic entities, a program must draw them using different pixel values and then assign the 
appropriate colors to these pixel values. You can assign a pixel value (color map index) to the 
draw value attribute, the text value attribute, the text background value attribute, and the fill 
value attribute. 

In within-GPR mode, you must call GPR routines to assign values to, or read values from, the 
color map. 



14.1.1. The Color Map: A Set of Color Values 

The color map is a display feature, not an attribute. This means that you cannot specify a color 
map in a metafile. However, the color map can be stored as tag data and read by an application 
program. You can specify only one color map for the display. 

A color map is a set of color values, each representing a color and intensity. A color value is an 
encoding of a particular visible color/intensity, based on the RGB (red/green/blue) color model. 
The RGB color model defines red, green, and blue as primary colors. All other colors are 
combinations of these primaries, including the three secondary colors (cyan, magenta, and 
yellow). 

Each color value consists of three component values, each a real number in the range 0.0 to 1.0. 
The first real number is the value for the red component of the color; the second, the green 
component; and the third, the blue component. A value of 0.0 specifies the absence of the 
primary color, and a value of 1.0 specifies full intensity of that primary color. 

On a color display, the red, green, and blue component values are displayed as accurately as 
possible, depending on the possible color values available on the node. For a detailed description 
of color and display configurations, see Programming with DOMAIN Graphics Primitives. 

On a monochrome display, you may either assign black (0.0, 0.0, 0.0) to and white (1.0, 1.0, 
1.0) to 1, or vice versa. 

If all three component values are equal, the color value is a shade of gray, as Table 14-1 shows. 
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Table 14-1. Example of Gray- Scale Color Values and Visible Intensities 



Color Value 


Visible Color/Intensity 


R value 


G value 


B value 


wHite 

light gray 
medium gray 
dark gray 
black 


1.0 

0.75 

0.5 

0.25 

0.0 


1.0 

0.75 

0.5 

0.25 

0.0 


1.0 

0.75 

0.5 

0.25 

0.0 



A color map consists of a set of color map entries; each entry is a color value associated with an 
index. Though the association between color values and visible colors/intensities cannot be 
changed, a program can establish and change the association between indexes and color values by 
changing the entries in the color map. In this way, a program can select the set of 
colors/intensities to constitute a color map for a particular application, and associate them with 
particular indexes. 

For an eight-plane color display, the color map has 256 entries, with index values 0-255. For a 
four-plane color display, the color map has 16 entries, with index values 0-15. For all displays, 
all entries are set to default values at the initialization of the 2D GMR package (see Figure 14-1). 
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8 PUNES, WITH COLOR MAP 



RED 



GREEN 



BLUE 



256 

SIMULTANEOUS 

COLORS 




DIM 
YELLOW 



Figure 14-1. The Pixel Value Used as an Index into the Color Map 
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Table 14-2 shows the default color map. 

Table 14-2. Default Color Map 



Monochromatic displays have only the first two color map entries 
Four-plane color displays have only the first sixteen color 
map entries. 



Color Table 


Color Value 


Resultant Visible 


Index 




Color/Intensity 




RGB 







0.0 0.0 0.0 


black 


1 


1.0 1.0 1.0 


white 


2 


0.0 1.0 0.0 


green 


3 


0.0 0.0 1.0 


blue 


4 


0.0 1.0 1.0 


cyan 


5 


1.0 1.0 0.0 


yellow 


6 


1.0 0.0 1.0 


magenta 


7 


1.0 1.0 1.0 


white 


8-15 


Contain colors used by the Display Manager 




to display windows . 
1 


16-255 


0.0 0.0 0.0 


black 



In direct mode, a program cannot modify color map entries and 7-15. Thus, the color map 
entries that may be changed are the following (Table 14-3): 



Table 14-3. Color Map Entries and Mode 





Borrow mode 


Direct Mode 


Monochromatic display 
4-plane color display 
8-plane color display 


0-1 

0-15 

0-255 


0-1 
1-6 
1-6. 16-255 
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14.1.2. Changing the Color Map 

Functions : 

GM_$D ISPLAY_SET_COLOR_MAP 
GM_$D I SPLAY_I NQ_COLOR_MAP 

GM_$DISPLAY_SET_COLOR_MAP changes a specified number of values in the color map. 
GM_$DISPLAY_INQ_COLOR_MAP retrieves a specified number of values in the color map. 

14.2. Using Viewport Techniques 

Functions : 

GM_$VIEWFORT_SET_BACKGROUND_VALUE 
GM_$VIEWFORT_INQ_BACKGROUND_VALUE 

As discussed in Section 13.9, attribute blocks can be assigned to attribute classes for individual 
viewports. The attribute class assignment can include a plane mask. If the plane mask assigned 
to attribute class 1 does not enable all planes in the GM bitmap, the following occurs. Not all 
planes are cleared before displaying into that viewport. (This is true for borrow, direct, and main- 
bitmap modes). You can use this characteristic to include a background grid that is not 
constantly erased and redrawn. This technique also makes it possible to superimpose two 
segments into the same viewport. 

The following describes some additional techniques to use with viewports. 

GM _$VIEWPORT_ SET _ BORDER _ SIZE sets the border size of the current viewport to the 
specified values, either in pixels or in fraction-of-bitmap coordinates. This routine sets sizes of 
the four edges independently, for each viewport. 

The default border type is in pixels, and the default width is 1,1,1,1. Viewport borders are drawn 
with color value 1 for compatibility with monochrome nodes. Also for this compatibility, the 2D 
GMR package sets the color map for color value 1 to white. 

With a color node, you may want to use the viewport background color to differentiate viewports 
from the overall display or the window background. Changing the color map to black is usually 
not practical because the cursor is also set to color value 1. An alternative is to create the 
viewport, set the border width to pixels, and then refresh the viewport. 

To change the viewport background value, you can use a procedure like the following: 

® Assign a background pixel value for each viewport. The default is 0. The pixel value 
displayed is affected by the plane mask assigned to attribute class 1. 

® Change the color by changing the color map. The default fill and text background 
values are -2. This sets them equal to the viewport background value. 

GM_$VIEWPORT_ SET _ BACKGROUND _ VALUE sets the pixel value used for the 
background of the specified viewport. GM_$VIEWPORT__INQ_ BACKGROUND _ VALUE 
returns the pixel value set for the background of the specified viewport. 
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14o3« Program with Advanced Viewing Techniques 

The following program changes the color map values; assigns a plane mask to viewports; displays 
a grid; changes the plane mask; assigns viewport background values; displays segments in more 
than one viewport; closes the file; and terminates the package. 

PROGRAM course6; 

%NOLIST; 

%INCLUDE ' /sys/ins/base . ins . pas ' ; 

%INCLUDE ' /sys/ins/time . ins . pas ' ; 

%INCLUDE '/sys/lns/gmr. ins .pas' j 

^INCLUDE '/sys/ins/pfm. ins .pas' : 

%LIST; 

CONST 

gm_def ault_aclass = 1; 

repeats = 10; 
space = 25; 
one_second = 250000; 

VAR 



bitmap_size 

St 

b 

vpi(i2 
vpidS 
vpid4 

ablockid 

k 

m 

n 

color_array 

file_id 
sidi 

sid3 
sid4 
ptl 
pt2 

trans 1 
rtransl 



gm_$pointl6_t; 
status_$t; 

gm $boiindsreal t; 



INTEGER; 

INTEGER; 
INTEGER; 



INTEGER; 
ARRAY [ 8 

INTEGER ; 



15 ] OF gm_$color_entry_t: 



gm_$segment_id_t ; 



gm_$pointl6_t; 
gm_$pointreal t; 



PROCEDURE check 

( IN status : status_$t 
); 

BEGIN 

IF status. all <> status_$ok 
THE:n pfm_$error_trap( status ); 
END; 
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PROCEDURE wait 

VAR 

pause : tlme_$clock_t; 
status : status_$t; 
BEGIN 

pause . low32 := 5 * one_second; 
pause. highie := 0; 
time_$¥ait 

( time_$relative 

. pause 

, status 

); 
check ( status ) ; 
END; 



< Wait five seconds. > 



BEGIN 



bitmap_size .X := 1024; 
l)itmap_size .y := 1024; 

gm_$lnit 

( gm_$borrow 
, stream_$stdout 
, bitmap_size 
. 8 
- St 

); 

gm__$f ile_create 
( 'gmfile' 
6 

gm_$overwrite 
gm_$lw 
file_id 

St 

); 

gm_$segment_create 
( 'grid' 
, 4 

. sidl 
, St 

); 

ptl .X := 0; 
FOR m := 1 TO 8 
DO BEGIN 

ptl.x := ptl .X + 100; 
ptl.y := 0; 
FOR n := 1 TO 8 
DO BEGIN 

ptl.y := ptl.y + 100; 
gin_$rectangle_16 
( ptl 
, ptl 

. St 

); 



•C Initialize the 2D GMR package . > 



< Create a file . > 



< Create segment 'grid. ' > 



■C 'Grid' points are zero-sized rectangles. > 
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END; 



END; 



gm_$segment_close 
( TRUE 
, St 

); 



{ Close segment 'grid. ' > 



b.xmin := 0.0; 
b.ymln := 0.0; 
b . xmax : = 0.49; 
b . ymax : = . 49 ; 
gm_$viewport_set_bounds 

( b 

. St 

); 

b.xmin := 0.51; 
b.ymin := 0.0; 
b . xmax : = 1.0; 
b.ymax := 0.49; 
gm_$vie¥port_create 

( b 

. vpid2 

, St 

); 



-C Shrink viewport 1 . > 



■C Create viewport 2. > 



b.xmin := 0.0; 
b.ymin := 0.51; 
b.xmax := 0.49; 
b . ymax : = 1.0; 
gm_$viewport_create 

( b 

. vpid3 

. St 

); 



< Create viewport 3. > 



b.xmin := 0.51; 
b.ymin := 0.51; 
b . xmax : = 1.0; 
b . ymax : = 1.0; 
gm_$viewport_create 

( b 

, vpid4 

. St 

); 



i. Create viewport 4. > 



FOR k := 8 TO 15 

DO WITH color_arrayC k 3 

DO BEGIN 

red := 1.0; 

green := 1.0; 

blue := 0.0; 

END; 



-C Red + green = yellow. > 



gm_$display_set_color_map 
( 8 
. 8 
, color_array 



"C Set color values 8 to 15 to yellow. > 



Advanced Display Techniques 



14-8 





, 


St 










) 










gm_ 


$abloclc 


create 






" ( 


1 










^ 


ablockid 








, 


St 










) 










gm_ 


_$at)lock_set_ 
( ablockid 


_draw_ 


value 




, 


9 










^ 


St 










) 











gm_$ablock_assign_display 
( gin_default_aclass 
. ablockid 
, St 

); 

gm_$display_f ile 
( st 
); 

wait; 



gm $ablock copy 
( 1 


. ablockid 


, St 

); 


gm_$ablock set plane_mask 
( ablockid 


. TRUE 


. [ .. 2 ] 


. St 

); 


gm $segmeiit create 
( 'box' 


. 3 


, sid2 


, St 

); 


ptl.x 
ptl.y 
pt2.x 
pt2.y 
gm $rec 

( I 

■ I 
, I 


= 0; 
= 0; 
= 10; 
= 10; 

:tangle_16 
)tl 

3t2 

^ALSE 


); 


3t 



< Create an ablock. } 



■C For the ablock. set the draw value to 9 . > 



< Assign the ablock to the default aclass . > 



< Display 'grid' in viewport 4. > 

■C Wait a moment . > 

-C Reset the ablock to default attributes. > 



■C For the ablock. set plane mask to [0.1.2]. > 



■C Create segment 'box. ' > 



< Add a rectangle to 'box.' > 



gm_$segment_close 



< Close segment 'box.' > 
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( 


TRUE 






, 


St 






). 






gm_ 


$segment 


create 




~ ( 


'row' 

3 

sid3 

St 






) 







< Create segment 'row. ' } 



transl .y := 0; 
transl.x := 0; 
FOR k := 1 TO repeats 
DO BEGIN 

transl.x := transl.x + space; 
gm_$instance_translate_2dl6 
( sid2 
, transl 
. St 
); 
END; 



-C Instance segment 'box* into segment 'row. '> 



gm_$segment_close 
( TRUE 

. St 

); 



< Close segment 'row. ' > 



gm_$segment_create 
( 'block' 
, 5 

. sid4 
, St 

); 



{ Create segment 'block. ' } 



transl .y := 50; 

FOR k := 1 TO repeats 

DO BEGIN 

transl .x := k ; 
transl. y := transl. y - space; 
gm_$instance_translate_2dl6 
( sidS 
, transl 

. St 

); 

END; 



< Instance segment 'row' into segment 'block. ' > 



gm_$segment_close 
( TRUE 
. St 

); 



■C Close segment 'block. ' > 



gm_$display_segment 
( sld4 
. St 
); 



-( Display segment 'block' in viewport 3. > 



wait. 



■C Wait a moment. > 
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rtransl .x := 0.5; 

rtransl.y := 1.0; 

gm_$view_scale 
(0.25 
, rtransl 
. St 

); 



< For viewport 3, zoom out. > 



rtransl .x := -0.06; 
rtransl .y := 0.0; 
FOR k := 1 TO 5 
DO gm_$view_translate 

( rtransl 

, St 

); 



-C For viewport 3, pan from left to right. > 



rtransl .x := 0.5; 

rtransl .y := 0.5; 

FOR k ;= 1 TO 5 

DO gm_$vlew_scale 
(0.85 
, rtransl 

. St 

); 



-C For viewport 3, pan diagonally towards > 
< the lower left. > 



wait; 



■C Wait a moment . > 



gm_$viewport_set_background_value < For viewport 2, set the } 



( vpid2 
, 2 

, st 
); 



■C background value . > 



gm_$viewport_select 
( vpid2 
. St 

); 



< Select viewport 2. > 



gm_$display_segment 
( sid3 
. St 
); 



-C Display segment 'row' in viewport 2. } 



wait, 



{ Wait a moment. > 



gm_$viewport_set_background_value { For viewport 3. set background > 
( vpid3 -C value to 2. > 

, 3 
. st 
); 

gm_$viewport_select 
( vpidS 
. st 
); 

gm_$display_segment 
( sid4 
, st 



■C Select viewport 3. > 



{ Display segment 'block' in viewport 3. } 
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); 

wait; 

gm_$file_close 
( TRUE 

, St 

); 

gm_$terminate 
( St 
); 

END. 



{ Wait a moment. > 
< Close the file. > 

{ Terminate the 2D GMR package . > 
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Chapter 15 
Prograinmmg Techniques 



This chapter presents techniques for using tags and for optimizing performance when you use the 
2D GMR package. Some of the relationships of the DOMAIN Core Graphics, the DOMAIN 
Graphics Primitives package and the DOMAIN 2D GMR Resource package are discussed. 



15.1, Using Tags 

Functions : 

GM_$TAG 
GM_$TAG_LOCATE 

Tags provide a mechanism to access the database at a particular place. For example, you may 
have another database running alongside the 2D GMR package. You can use a tag to flag a place 
in a segment for accessing information in another database. 

GM_$TAG inserts a comment into the metafile. 

GM_$TAG_ LOCATE locates a comment within a specified range of segments in the current 
metafile. The routine returns the identification of the lowest-numbered segment that the 
comment is found in. 

This routine uses the wildcard options of the command line parser. For a description of the 
command line parser, see the DOMAIN System Command Reference. 



15.2. Program Techniquej Using Tags 

Tags are especially usful with large metfiles. The following program fragment illustrates the use 
of tags. 



< The current segment is 'assembly_sid . ' A part is instanced into 

the assembly, followed by a tag with the part's unique part number. > 

gm_$instance_translate_2dl6 

( part_sid -C Segment defining part > 

, location -C Location of part > 

, status 
); 

gm_$tag 

( part_number < ASCII string with part number > 

, part number_len { Length of ASCII string > 
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status 



): 



< Later, the user needs to find the part with the given part number: > 



gm_$tag_locate 

( part_number 
part_number_len 


gm_$max_segment - 1 
assembly_sid 
status 
); 



•C ASCII string with part number > 
■C Length of ASCII string } 
{ Lacking more specific information. > 
i search all segments } 

< Output the segment id containing the 
part . > 



15. 3» Optimizing Performance 

This section presents some techniques for optimizing performance in the applications you build 
with the 2D GMR package. 



15.3.1. Sorting by Location in the Picture 

The 2D GMR package keeps track of the rectangular bounds of each segment in a segment header 
attached to the segment data. When displaying a file, the 2D GMR package can therefore rapidly 
reject segments that do not overlap the current viewport, without examining individual 
commands within those segments. 

You can, therefore, improve performance by sorting order-independent commands into segments 
based on their location in the picture. By grouping commands into segments with relatively 
small bounds, you can increase the number of segments that can be completely ignored during 
display. 

The 2D GMR package cannot sort data for you because the package assumes that commands 
must be executed in the order you specify. 



15.3.2. Segment Size 

For files with many (hundreds or thousands) of segements, use unnamed segments. This avoids 
the overhead of checking for duplication of names. 
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15.3.3. Rectangles and Rotations 

If you regularly apply rotations other than 90 or 180 degrees to rectangles, use the 
GM_$POLYLINE... routines, not the GM_$RECTANGLE... routines. With rectangle routines, 
the picture is not drawn incorrectly; however, the picture is displayed faster with polyline 
commands. 



15.3.4. Compacting Files 

To reduce storage space for old files, you can develop a compacting utility using 
GM_$FILE_ COMPACT. For a description of this routine and an example of such a utility, see 
GM_$FILE_ COMPACT in DOMAIN System Call Reference, Volume 1. 



15.3.5. Releasing and Acquiring the Display 

The listing of insert files at the top of the program " hotel. gm" in Appendix D includes 
gpr.ins.pas. This file gives access to the DOMAIN Graphics Primitives (GPR) routines. In 
general, the mixing of 2D GMR and GPR is not recommended unless you specify within-GPR 
mode with the routine GM_$INIT. Here the GPR routine provides the best way to release the 
display that 2D GMR must acquire. The GPR routine releases the display to allow writing 
output to a stream. 

Mixing 2D GMR and GPR calls in other ways or in other contexts is not recommended or 
supported. 



15.3.6. Long Identifiers 

In C and FORTRAN, identifiers may be no longer than a maximum of 32 characters. In C 
programs, the compiler truncates the name to 32 characters. In FORTRAN programs, you need 
to shorten the following routine names to 32 characters as illustrated: 



12345678901234567890123456789012 I 34567890 



GM_$ABLOCK_INQ_FILL_BACKGROUND_V | ALUE 

GM_$ABLOCK_INQ_TEXT_BACKGROUND_V | ALUE 

GM_$ABLOCK_SET_FILL_BACKGROUND_V | ALUE 

GM_$ABLOCK_SET_TEXT_BACKGROUND_V | ALUE 

GM_$INQ_INSTANCE_TRANSF0RM_2DREA | L 

GM_$INQ_INSTANCE_TRANSLATE_2DREA t L 

GM_$VIEWPORT_INQ_BACKGROUND_VALU I E 

GM $VIEWFORT SET BACKGROUND VALU | E 



15.3.7. Color Map on Color Nodes 

The 2D GMR package currently sets color 1 to white on color nodes for portability of 
applications developed on monochrome nodes. The viewport borders and the cursor are drawn 
with color 1. For nonwhite cursors and viewport boundaries on color nodes, use 
GM $DISPLAY_ SET _ COLOR _MAP to respecify color 1. 
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When 2D GMR terminates, it currently resets color 1 to whatever it was when the package was 
initialized. This is true of color nodes only. If you use 2D GMR in borrow mode, the entire color 
map is reset when the packge terminates. (The resetting is not by 2D GMR, but by GPR.) 



15.3.8. Fault Handlers 

The 2D GMR package has its own "clean-up" handler that terminates 2D GMR whenever faults 
are encountered. It is not necessary for an application to install its own fault handler for this 
purpose. In fact, an application-installed fault handler will not work because 2D GMR will no 
longer be initialized by the time the fault handler is called. 



15.4. For Users of Both 2D GMR and GPR 

The 2D GMR functions are similar to DOMAIN Graphics Primitives (GPR) in many ways. The 
2D GMR package has new routines for handling files, segments, and viewing. 

There are a few major differences between 2D GMR routines and similar GPR routines. Two 
examples are the coordinate systems used and the use of defined points, rather than current 
position. 

Coordinate Systems 

The 2D GMR package uses the coordinate system that is standard in mathematics textbooks (+x 
is to the right; +y is up). This is different from GPR, which like most raster display devices uses 
4-y as down). 

Thus, if only positive coordinates are used, (0,0) is at the bottom left of the bitmap, not the top 
left as in GPR. 

The only cases in which 2D GMR uses +y as down is in its definition of cursor patterns and in 
the output of GM_$PRINT... routines. 

Defined Points and Current Position 

The 2D GMR package requires that all coordinates be specified for each command. There is no 
"current position" kept from one command to the next, as there is in GPR. Thus, with the 2D 
GMR segment, you can insert or delete commands without affecting the interpretation of 
coordinate data in other commands in the segment. 

Number of Planes Initialized 

The input parameter to GM_$INIT is the number of planes to be initialized (that is, 1 or 8), not 
the number of the highest plane, as in GPR_$INIT (that is, or 7). 



15.5. For Previous Users of DOMAIN Core Graphics 

The 2D GMR functions are similar to Core in many ways. Both allow you to define coordinates 
in one coordinate system and display them in another. 
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There are a few major differences between 2D GMR routines and similar Core routines. Two 
examples are the number of segments displayed and the use of defined points rather than current 
position. 

Segments Displayed 

In Core, multiple segments can be displayed in one viewport. 

The 2D GMR package keeps only one segment in a viewport. If you wish to display more than 
one segment in a viewport, you must create a new segment and insert into it instances of all the 
segments you want to display. 

When you use the 2D GMR package and specify within-GPR mode, you may display multiple 
segments in the GPR bitmap. 

Defined Points and Current Position 

The 2D GMR package requires that all coordinates be specified for each command. There is no 
"current position" kept from one command to the next, as there is in Core. Thus, with the 2D 
GMR segment, you can insert or delete commands without affecting the interpretation of 
coordinate data in other commands in the segment. 

Temporary Segments 

In Core, a temporary segment is put on the screen. No copy of the segment is kept. 

In 2D GMR, a "temporary segment" is different. It is a segment that is stored like any other 
segment while the file is open; however, it is deleted when the file is closed. 

Core Imaging and Viewing Transformations 

In Core, you can specify a viewing transform to be applied to data that you have already 
supplied to the Core package. This transform is applied before the Core package stores the data 
as a display list. Core also provides an image transform, which is applied to stored data at 
display time. 

2D GMR provides no mechanism analogous to the Core viewing transform described in the 
previous paragraph. In the 2D GMR package, the data is always stored untransformed as you 
supply it. 

Incremental Display 

In Core, every time you execute a command, the display is immediately updated. 

In GM_$REFRESH_WAIT (default) or GM_$REFRESH_ INHIBIT refresh states, the display 
is not updated each time you add data to the file. Incremental display can occur only in 
GM_$REFRESH_UPDATE and GM_$REFRESH_ PARTIAL refresh states, and only in 
GM $BORROW and GM $DIRECT mode. 
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Appendix A 
Glossary 



Ablock See Attribute block. 

Aclass See Attribute class. 

Attribute A characteristic of the manner in which a primitive graphic operation is to be 

performed (for example, line type or text value). 

Attribute block A data structure that holds a collection of values of attributes. 

Attribute class A means for referring to a collection of attribute values from within a metafile, 
with the particular attribute values defined elsewhere in the file or when the 
file is displayed. 

Attribute command 

A command in a metafile that affects the form in which subsequent primitive 
commands are to be displayed. 



Bit plane 



Bitmap 



A one-bit-deep layer of a bitmap. On a monochromatic display, displayed 
bitmaps contain one plane. On a color display, displayed bitmaps may contain 
more planes, depending on the hardware configuration and the number of bits 
per pixel. 

A three-dimensional array of bits having width, height, and depth. When a 
bitmap is displayed, it is treated as a two-dimensional array of sets of bits. 
The color of each displayed pixel is determined by using the set of bits in the 
corresponding pixel of the frame-buffer bitmap as an index into the color table. 



Bitmap coordinates 

Coordinates of points inside the GM bitmap, expressed as fractions of the GM 
bitmap. The lower left corner is referred to as (0.0, 0.0); the upper right corner 
as (1.0, 1.0). Note that if the GM bitmap is not square, the units in the x and 
y directions are different. 

Borrow mode A mode for use with the 2D GMR package whereby a program borrows the 
entire screen from the Display Manager and performs graphics operations by 
directly calling the display driver. The display is on the full screen, which is 
temporarily borrowed from the Display Manager. 

Button A logical input device used to provide a choice from a small set of alternatives. 

A physical device of this type is the selection buttons on a mouse. 

Color map See Color table. 

Color table A set of color table entries, each of which can store one color value. Each color 

value contains red, green, and blue component values. Each entry is accessed 
by a color table index. 
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Color table entry One location in a color table. Each entry stores one color value that can be 
accessed by a corresponding color table index. 

Color table index An index to a particular color table entry. 

Color value The numeric encoding of a color. A color value is stored in a color table entry. 

Each color value consists of three component values: the first stores the value 
of the red component of the color, the second stores the value of the green 
component of the color, and the third stores the value of the blue component. 
Each component value is specified as a real number in the range 0.0 to 1.0, 
where 0.0 is the absence of the primary color and 1.0 is the full intensity color. 

Command A single element of a picture as stored in a metafile. Commands are categorized 

as primitive commands, attribute commands, instance commands, and tag 
commands. 

Current command 

The command in the current segment after which new commands are to be 
inserted. It is also the command that you can inquire about, replace, or delete. 
When you open a segment, the last command becomes the current command, 
allowing new commands to be appended. You may use 

CM _$PICK_ COMMAND to change the current command. 

Current file The file currently being operated on. The current file can be changed by 

selecting another previously opened file or by opening (creating) an additional 
file. 

Current picked segment 

The segment selected by the pick-segment operation. It is used as a base for 
further pick-segment operations. 

Current segment 

The segment currently open for editing. 

Current viewport The currently selected viewport. The current viewport can be changed by 
selecting another existing viewport or by creating a new viewport. 

Direct mode A mode for use of the 2D GMR package whereby the package performs 

graphics operations in a window borrowed from the Display Manager. Direct 
mode allows graphics programs to coexist with other activities on the screen. 

Display The entire monitor screen. 

Display Manager 

The program that manages the display and allocates Display Manager 
windows. 

Display Manager window 

One section of the display, provided by the Display Manager. This window 
does not include the edges reserved by the Display Manager. 

File See Metafile. 
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Font One set of alphanumeric and special characters. The font in which text is to be 

displayed is determined by the package using the user-selected font family and 
text size attributes. 

Font family A list of similar fonts of differing size. The 2D GMR user creates an ASCII file 

containing this list. 

Font family file An ASCII file listing the fonts in the font family, one font per line. 

GM bitmap The bitmap in which the 2D GMR package is initialized. In direct mode, this 

is part of the Display Manager window in which the package was initialized. In 
borrow mode, this is the entire current display. In main-bitmap mode, this is a 
main-memory bitmap. 

Input device A device such as a function key, touchpad, or mouse that enables a user to 

provide input to a program. 

Input event An input primitive that is created by a user's interaction with a device such as 

a keyboard, button, mouse, or touchpad. 

Instance command 

A command in a metafile that calls for another segment to be displayed, with a 
particular transformation applied. This is similar to a subroutine call. 

Instanced segment The segment referred to by an instance command in another segment. 

Instancing segment 

The segment that contains the instance command that refers to the instanced 
segment. 

Keyboard A logical input device used to provide character or text string input. One 

physical device of this type is the alphanumeric keyboard. 

Line style An attribute that specifies the style of lines and polylines (for example, solid or 

dotted). 

List of picked segments 

The linked sequence of instancing and instanced segments selected by a series of 
pick-segment operations, starting with the viewport primary segment (or 
primary segment in no-bitmap mode) and ending with the current picked 
segment. 

Locator A logical input device used to specify one position in coordinate space (for 

example, a touchpad, data tablet, or mouse). 

Logical input device 

An abstraction that refers to any of a group of physical input devices that 
provide similar input data. For example, the logical input device "button" can 
refer to physical buttons on a mouse, or to physical buttons on a data tablet 
puck. 
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Mode 



Main-bitmap mode 

A mode for use with the 2D GMR package whereby a program runs in a 

bitmap allocated in main memory, without using the display. 

A device-independent collection of picture data that can be displayed. (Also 
referred to as a file.) 

One of four modes for use of the 2D GMR package, selected when the 2D GMR 
package is initialized. See Borrow mode, Direct mode. Main-bitmap mode, and 
No-bitmap mode. 



Modeling routines Graphics metafile routines used to insert commands into metafiles or to edit 
metafiles. 

No-bitmap mode A mode for use with the 2D GMR package whereby a program runs without a 
main-memory or display bitmap. Viewing routines may not be performed in 
this mode. 

Open file Any of the files that have been opened during this session and have not yet 

been closed. More than one file may be open at one time. 

Pick aperture The region in segment coordinate space within which pick routines will search 
for commands and segments. 

Pick mask A number that is compared bit by bit with a segment's pickable value to 

determine if the segment is pickable. If any bit is "1" in both the segment's 
pickable number and the pick mask, the segment may be picked (see also Pick 
threshold and Pick aperture). If not, the segment is not picked. 

Pick operation The process of selecting commands or segments. 

Pick threshold A number that is compared to a segment's pickable value to determine if the 
segment is pickable. If the segment's pickable number is greater than or equal 
to the pick threshold, the segment may be picked (see also Pick mask and Pick 
aperture). If not, the segment is not picked. 

Pickable value A number assigned to each segment that is used to determine whether a 
segment is to be considered during pick-segment operations. 



Picture 



The entire contents of a file as drawn; it may be larger or smaller than either 
the GM bitmap or viewport. 



Picture element A single element of a two-dimensional displayed image or of a two-dimensional 
location within a bitmap. It is commonly called a pixel. 

Pixel See Picture element. 

Pixel value The set of bits at a two-dimensional location within a bitmap. A pixel value is 

used as an index to the color map. 

Polyline A linked set of line segments. 
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Primary segment The segment that is the logical start of the file for display purposes. The 
routine GM_$DISPLAY_FILE assumes that you wish to display this segment 
and all of the segments that it instances. 

Primitive command 

A command in a metafile that describes a single least divisible graphic 
operation of a stored picture (for example, lines, polylines, and text). See also 
User-defined primitive. 

Routine One of the procedures or functions of the 2D GMR package. Routines are 

categorized as modeling routines and viewing routines. 

Scan line A row of pixels; one horizontal line of a bitmap. 

Segment A collection of commands in the metafile that can be referred to as a group. 

See also current segment. 

Segment-exponent format 

A format for storage of coordinate data, similar to floating point. Instead of 
an exponent and a mantissa for each coordinate, there is one exponent for the 
entire segment and a separate 16-bit or 32-bit mantissa for each coordinate. 

Tag command A command in a metafile that contains a comment. The comment data can be 
retrieved by the user, but is ignored when the file is displayed. 

User-defined Primitive 

A primitive routine, exclusive to within-GPR mode. This type of routine is 
defined and specified by the user. 

View The part of a picture that is currently seen through a viewport. For example, 

translating or scaling a view affects what is visible through the viewport. 

Viewing routines Graphics metafile routines used to control the form in which metafiles are 
displayed. 

Viewport All or part of the window, excluding its border if one exists. The viewport is 

the physical "hole" in the window through which graphic output or other 
processes are visible. Moving the viewport within the GM bitmap does not 
scale the view. 

Viewport primary segment 

The segment currently displayed within a viewport. Other segments that are 
instanced directly or indirectly by this segment may also be displayed. 
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Appendix B 

Keyboard Charts 



The following two charts and figures give the 8-bit ASCII values generated for two DOMAIN 
keyboards: 880 and low-profile. These charts include characters used in keystroke events. The 
columns represent the four highest-order bits of an 8-bit value. The rows represent the four 
lowest-order bits of an 8-bit value. For a more complete description of conventions for naming 
keys, see the DOMAIN System Command Reference. 
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Figure B-1. Low-Profile Keyboard Chart - Translated User Mode 
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Figure B-2. Low-Profile Keyboard 



B-3 Brogram to Read the Contents of a Metafile 




Figure B-S. 880 Keyboard 
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Figure B~4. 880 Keyboard Chart - Translated User Mode 
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Appendix C 
Program to Read the Contents of a Metafile 



The following program prints out the entire contents of a metafile in a form you can read. 

■{ tread. pas > 

program tread; 

%nolist; 

%include '/sys/lns/base . ins . pas ' ; 

%lnclude '/sys/lns/error . ins . pas * ; 

^include '/sys/ins/gmr . ins .pas ' ; 

%list; 

VAR 

St : status_$t; 

name : array [1 . . 100] of char; 

Iname : integer; 

file_id : integer; 

num_seg, max_seg_id, seg, seg_id : gm_$segment_id__t; 

ctype : gm_$command_type_t; 

dtype : gm_$data_type_t ; 

i,j : integer; 

k : integer32; 

r : real; 

ptl, pt2 : gm_$pointl6_t; 

rptl, rpt2 : gm_$pointreal_t; 

rot : gm_$rotate_real2x2_t; 

pt : gm_$point_arrayl6_t; 

rpt : gm_$point_arrayreal_t; 

fill, close : boolean; 
style : gm_$line_style_t; 
pattern : gm_$draw_pattern_t; 
mask : gm_$plane_mask_t; 
rotate : real; 



procedure check; < internal > 

begin 

if ( St. all <> status_$ok ) then 

error_$print (st) ; 
end; < procedure check > 



BEGIN 

gm_$init(gm_$no_bitmap, l,ptl, l,st) ; check; 

gm_$f ile_open('gmf ile' , 6,gm_$wr,gm_$lw,f ile_id,st) ; check; 

gm_$segment_inq_count(num_seg, max_seg_id, st) ; check; 
for seg := to max__seg_id do 
begin 
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gm_$segment_inq_name(seg,name, lname,k,st) ; 
if ( St. all = gm_$segmeiit_id_invalid ) then 

NEXT; 
check; 
writeln; 
wrltelnC segment", seg, * '. name : Iname) ; 

gm_$segment_open(seg,st) ; check; 
gm_$pick_command(gm_$start,st) ; check; 
gm_$pick_command(gm_$step,st) ; check; 
while ( St. all = ) do 
begin 

gm_$inq_command_type(ctype, dtype, st) ; check; 
case ( ctype ) of 
gm_$taclass : 
begin 

gm_$inq_aclass (i , st) ; 
writeln C'aclass '. i) ; 
end; 
gm_$tcircle_2d : 
begin 

if ( dtype = gm_$16 ) then 
begin 

gm_$inq_circle_16(ptl,i.fill,st) ; check; 
writelnC 'circle 16 '. ptl.x, ptl.y); 
writelnC ', i) ; 

end 
else if ( dtype = gm_$32 ) then 
begin 

gm_$inq_circle_real(rptl.r, finest) ; check; 
writelnC 'circle real ', rptl.x, rptl.y); 
writelnC ', r) ; 

end; 
if ( fill ) then 

writelnC' filled') 

else 

writelnC not filled'); 

end; 
gm_$tdraw_raster_op : 
begin 

gm_$inq_draw_raster_opCi-st) ; check; 
writelnC draw raster op ', i) ; 
end; 
gm_$tdrawstyle : 
begin 

gm_$inq_draw_styleCstyle, i, pattern, j ,st) ; check; 
writelnC draw style ', style, i) ; 
end; 
gm_$tdrawvalue : 
begin 

gm_$inq_draw_value Ck, st) ; check; 
writelnC draw value ', k) ; 
end; 
gm_$tf illbvalue : 
begin 

gm_$inq_f ill_background_value Ck, st) ; check; 
writelnC fill background value ', k) ; 
end; 
gm_$tf illvalue : 
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begin 

gm_$inq_f ill_value (k, st) ; check; 
writelnC'fill value ', k) ; 
end; 
gni_$tfontfamlly : 
begin 

gm_$inq_font_faniily(i,st) ; check; 
writelnC'font family '. i) ; 
end; 
gm_$t.instaace_scale_2d : 
begin 
if C dtype = gm_$16 ) then 

begin 

gm_$inq_instance_scale_2dl6(seg_id,r,ptl,st) ; check; 

writelnC' instance scale 2dl6 '. seg_id, r) ; 

writelnC *, ptl.x, ptl.y); 

end 
else if ( dtype = gm_$32 ) then 

begin 

gm_$inq_instance_scale_2dreal(seg__id,r,rptl,st) ; check; 

writelnC 'instance scale 2dreal ', seg__id, r) ; 

writelnC ', rptl.x, rptl.y); 

end; 
end; 
gm_$tinstance_trans_2d : 
begin 
if ( dtype = gin_$16 ) then 

begin 

gin_$inq_instance_translate_2dl6(seg_id,ptl.st) ; check; 

writelnC 'instance translate 2dl6 ', seg_id) ; 

writelnC *, ptl.x, ptl.y); 

end 
else if C dtype = gm_$32 ) then 

begin 

gm_$inq_instance_translate_2drealCseg_id,rptl, St) ; check; 

writelnC instance translate 2dreal ', seg_id) ; 

writelnC ', rptl.x. rptl.y); 

end; 
end; 
gm_$tinstance_transform_2d : 
begin 
if C dtype = gm_$i6 ) then 

begin 

gm_$inq_instance_transform_2dl6Cseg_id,rot,ptl, st) ; check; 

writelnC instance transform 2dl6 ' . seg_id) ; 

writelnC '. rot .xx,rot .xy.rot .yx, 

rot .yy) ; 

writelnC ', ptl.x, ptl.y); 

end 
else if C dtype = gm_$32 ) then 

begin 

gm_$inq_instance_transform_2drealCseg_id,rot,rptl,st) ; check; 

writelnC instance transform 2dreal *, seg_id) ; 

writelnC '. rot .xx.rot .xy.rot .yx, 

rot . yy) ; 

writelnC *- rptl.x. rptl.y); 

end; 
end; 
gm_$tplanemask : 
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begin 

gm_$inq_plane_mask(mask,st) ; check: 
writelnC 'plane mask '. Integerl6(mask)) ; 
end; 
gm_$tpolyline_2d : 
begin 
if ( dtype = gm__$16 ) then 

begin 

gm_$inq_polyline_2dl6 (i . pt , close . fill . st) j check; 

writelnC 'polyline 2dl6 ') ; 

for j := 1 to i do 

writelnC '. pt[j] .x, pt[j].y); 

end 
else if ( dtype = gm_$32 ) then 

begin 

gm_$inq_polyline_2dreal (i , rpt , close , fill , st) : check; 

writelnC 'polyline 2dreal '); 

for j := 1 to i do 

writelnC '. rpt[j].x, rpt[j].y); 

end; 
if ( close ) then 

writeC closed. ') 

else 

write (' not closed,'); 

if ( fill ) then 

writelnC filled') 
else 

writelnC not filled'); 
end; 
gm_$trectangle : 
begin 
if ( dtype = gm_$16 ) then 

begin 

gm_$inq_rectangle_16(ptl,pt2,f ill,st) ; check; 

writelnC 'rectangle 16 ', ptl.x, ptl.y); 

writelnC ', pt2.x, pt2.y); 

end 
else if C dtype = gm_$32 ) then 

begin 

gm_$inq_rectangle_realCrptl,rpt2, f ill,st) ; check; 

writelnC'rectangle real ' . rptl.x, rptl.y); 

writelnC '- rpt2.x< rpt2.y); 

end; 
if C fill ) then 

writelnC filled') 

else 

writelnC not filled'); 

end; 
gm_$ttag : 
begin 

gm_$inq_tagCname, Iname.st) ; check; 
writelnC tag ' . name.lname); 
end; 
gm_$ttext_2d : 
begin 
if C dtype = gm_$16 ) then 

begin 

gm_$inq_text_2dl6 Cptl , rotate . name . Iname . st) ; check; 

writelnCtext 2dl6 '. ptl.x, ptl.y); 
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writeInC ', rotate, name : Iname) ; 
end 
else if ( dtype = gm_$32 ) then 
begin 

gm_$inq_text_2drealCrptl, rot ate, name, Iname, st) j check; 
writelnC'text 2dreal ', rptl.x, rptl.y); 
writelnC* ', rotate, name: Iname); 
end; 
end; 
gm_$ttextbvalue : 
begin 

gm_$inq_text_background_value(k:,st) ; check; 
writelnC 'text background value ', k) ; 
end; 
gm_$ttextsize : 
begin 

gm_$inqL_text_size(r,st) ; check; 
writelnC 'text size ', r) ; 
end; 
gm_$ttextvalue : 
begin 

gm_$inq_text_valueCk,st) ; check; 
writelnC 'text value ', k) ; 
end; 
end; 
gm_$pick_commandCgm_$step,st) ; 
end; 
gm_$segment_closeCfalse,st) ; check; 
end; 

gm_$f ile_closeCtrue,st) ; check; 
gm_$terminate Cst) ; check; 
END. 



C-5 Program to Read the Contents of a Metafile 



Appendix D 
Program: Instances and Attributes 



The program in this appendix displays a file as it is being created and edited. The file creates the 
picture in Figure D-1. 

PROGRAM hotel; 

%NOLIST; 

^INCLUDE ' /sys/ins/base . ins . pas ' ; 

%INCLUDE ' /sys/ins/error . ins . pas ' ; 

%INCLUDE '/sys/ins/pfm. ins .pas' ; 

%INCLUDE ' /sys/ins/gmr . ins . pas * ; 

%INCLUDE ' /sys/ins/time . ins . pas ' ; 

%LIST; 



CONST 



one_second = 250000; 

five seconds = 5 * one second; 



VAR 



status 


status $t; 


file_id 


INTEGER; 


font file_id 


INTEGER; 


Sid scene 


gm $segment_id_t; 


sid_door 
sid_window 
Sid sign 
Sid tree 
sid_liouse 


gm_$segment_id_t; 
gm $segment id t; 
gm $segment_id_t; 
gm $segment_id_t; 
gm_$segment_id_t; 


pattern 

P 

center 

radius 


gm $draw_pattern t; 
gm_$point_arrayl6_t 
gm_$pointl6_t; 
INTEGER; 


i 


INTEGER; 



pause 



time $clock t; 



PROCEDURE check; 

BEGIN 

IF status. all <> status_$ok 
THEN pfm_$error_trap( status ); 
END; 



BEGIN 

p[ 1 ] .X := 1024, 



{ Intialize the 2D GMR package. > 



D-1 
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Figure D-1. A Picture Created Using Instances and Attributes 
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pC 1 3 .y := 1024; 
gm_$init 

( gm_$direct 

, stream_$stdout 

, p[ 1 ] 

, 8 

, status 

); 
check; 



gin_$f ile_create 
( 'hotel. gm' 
8 

gin_$overwrite 
gin_$lw 
file_id 
status 
); 
check; 



< Create a 2D GMR file. } 



gm_$font_family_include 

( 'ffO' 

, 3 

, gin_$pixel 

. font_f ile_id 

. status 

); 
check; 



{ Load a font family. } 



gin_$data_coerce_set_real 
( gm_$32 
. status 

); 
check; 



< Set the data coerce function. } 



gin_$segment_create 

( •• 

. 

. sid_door 

. status 

); 
check; 



< Create the segment for the door. > 



pC 1 3 .X := 0; 
p[ 1 3 .y := 0; 
pC 2 3.x := 36; 
pC 2 3 .y := 80; 
gm_$rectangle_16 

( pC 1 3 

. p[ 2 3 

. TRUE 
. Status 
); 
check; 



■C Construct the door. > 



gm_$f i 1 l_value 
( 
, status 

); 



< Construct the door knob. > 
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check; 

pC 1 ].x 

pC 1 3 -y 

p[ 2 ] .X 

p[ 2 ] .y 



= 30; 
= 38; 
= 33; 
= 41; 



gm_$rectangle_16 



( 



); 
check: 



p[ 1 ] 
pC 2 ] 
TRUE 
Status 



gm_$ s e gme n t_c 1 o s e 
( TRUE 
, status 

); 

check; 



gin_$segmeiit_create 
( •• 



■C Create the segment for the windows. > 



, Sid 


window 


, status 


); 


check; 


p[ 1 ].x 


= 0; 


p[ 1 ].y 


= 0; 


pC 2 ] .X 


= 36; 


pC 2 ].y 


= 36; 


gm $rectangle 16 


( p[ 1 ] 


. p[ 2 ] 


, FALSE 


, status 


); 


check; 


p[ 1 ] .X 


= 0; 


p[ 1 ].y 


= 18; 


p[ 2 ] .X 


= 36; 


pC 2 ].y 


= 18; 


gm $polyline 2dl6 


( 2 


. P 


, FALSE 


. FALSE 


, status 


); 


check; 


p[ 1 ].x 


= 18; 


pC 1 ].y 


= 0; 


p[ 2 ] .X 


= 18; 


p[ 2 ].y 


= 36; 


gm $polyline 2dl6 


( 2 
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' p 

, FALSE 
, FALSE 
, status 
); 
check; 

gm_$segment_close 

( TRUE 

, status 

); 
check; 

gin_$segmeiit_create < Create the segment for the sign. > 

( •• 

. 

, sicl_sign 

. status 

); 
check; 

gm_$text_slze 

(14.0 

, status 

); 
check; 

p[ 1 ] .X := 0; 
p[ 1 ] .y := 0; 
gm_$text_2dl6 

( p[ 1 ] 

, 0.0 

, 'GRAND MOTEL* 

. 11 

, status 

); 
check; 

gm_$segment_close 

( TRUE 

, status 

); 
check; 

gm_$segment_create •( Create the segment for the house . > 

( " 

, 

, sid_house 

, status 

); 
check; 



p[ 1 ] .X 

pC 1 3y 
p[ 2 3.x 

pC 2 ].y 
gm_$rectangle_16 

( pC 1 3 
. p[ 2 ] 



= 0; i Build the house. } 

= 0; 
= 480; 
= 260; 
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FALSE 
status 



); 
check; 



pc 1 

pC 1 

p[ 2 
p[ 2 
p[33 



]y 

].x 

]y 



= -10 
= 255 
= 240 
= 380 
490; 



-C Build the roof . > 



p[3] .y := 255; 
gm_$polyline_2dl6 
( 3 

' P 

. FALSE 

. YMJSE. 
. status 
); 
check; 



pC 1 ] .X := 300. 
p [ 1 ] . y : = 350 , 
p[ 2 ] .X := 300; 
p[ 2 ] .y := 370. 
p[3] .X := 330, 
p[3] .y := 370, 
pC43 .X := 330; 
p[4] .y := 335; 
gm_$polyline_2dl6 
( 4 

' P 

. FALSE 
. FALSE. 
. Status 
); 
check; 

center. X := 240; 
center. y := 195; 
radius := 45; 
gm_$circle_16 

( center 

. radius 

. FALSE 

. status 

): 
check; 



< Build the chimney. > 



•C Build the round window. > 



P[ 
P[ 
P[ 
P[ 

pc 

P[ 
PC 

pc 



.X 

• y 

x 

• y 

x 

•y 

.X 

• y 



= center. X - radius, 

= center. y; 

= center. X + radius, 

= center. y; 

= center. x; 

= center. y - radius, 

= center. x; 

= center. y + radius, 



gm_$polyline_2dl6 
( 4 
. P 
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. TRUE 




. FALSE 




. status 




); 




check; 




pC 5 ].x 


= p[ 2 ].x; 




pC 5 ].y 


= p[ 2 ].y; 




p[ 2 ].x 


= p[ 3 ].x; 




p[ 2 ].y 


= pC 3 ].y; 




gm $polyline 2dl6 




( 2 




' P 




, FALSE 




. FALSE 




. status 




); 




check; 




gm $polyline 2dl6 




( 2 




. pC4] 




. FALSE 




. FALSE 




. status 




); 




check; 




p[ 1 ] .X := 222; 




p[ 1 ] .y := 0; 




gm_$instance_translate_ 


_2dl6 


( Sid door 




. pC 1 ] 




, status 




); 




check; 




p[ 1 ] .X := 50; 




p[ 1 ] .y := 40; 




gm_$instance_translate_ 


_2dl6 


( Sid window 




. p[ 1 ] 




. status 




); 




check; 




p[ 1 ] .X := 118; 




gin_$instance_translate 


_2dl6 


( Sid window 




. p[ 1 ] 




, status 




); 




check; 




p [ 1 ] . X : = 326 ; 




gin_$instance_translate 


_2dl6 


( Sid window 




. p[ 1 ] 




. sta 


tus 





< Instance and position the door. > 



"C Instance and position the windows. > 



D-7 



Program: Instances and Attributes 



); 

check; 

p[ 1 ] .X := 394; 
gm_$instance_translate_2dl6 

( sid_window 

, pC 1 ] 

. status 

); 

pC 1 ] .y := 180; 
gm_$instance_translate_2dl6 
( sid_wlndow 

. p[ 1 ] 
, status 
); 

p[ 1 ] .X := 326; 
gm_$instance_translate_2dl6 

( sid_windo¥ 

. p[ 1 ] 

, status 

); 
check; 

p[ 1 ] .X := 118; 
gin_$instance_translate_2dl6 

( sid_window 

, p[ 1 ] 

, status 

); 
check; 



p[ 1 3.x := 50; 
gin_$instance_translate_2dl6 

( sid_windo¥ 

. p[ 1 ] 

. status 

); 
check; 

p[ 1 ] .X := 172; 

p[ 1 ].y := 120; 
gm_$instance_translate_2dl6 
( sid_sign 

, p[ 1 ] 
. status 
); 
check; 



■C Instance and position the segment > 
■C for the sign. > 



gm_$segment_close 

( TRUE 

, status 

); 
check; 

gm_$segment_create 
( " 



■C Create the segment for the trees . > 
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, sid_ 


tree 


, status 
); 
check; 


p[ 1 3.x := 0; 
p[ 1 3.y := 0; 
pC 2 3 .X := 0; 
pC 2 3 -y := 150; 
gm $polyline 2dl6 
( 2 


' P 

, FALSE 


. FALSE 


, status 

); 
check; 


p[ 1 3.x 
p[ 2 3 .X 
gm $polyl: 
C 2 


= 12; 
= 12; 
Lne_2dl6 


- P 

, FALSE 


, FALSE 


, status 

); 
check; 


pC 1 3 .X := 6; 
pC 1 3 y := 200; 
gm $circle 16 

( pC 1 3 

, 50 


. FALSE 


. status 

); 
check; 


gm $draw style 
( gm_$dotted 
, 2 


, pattern 
. 


. status 


pC 1 3 .X 
p[ 1 3.y 

p[ 2 3 .X 

p[ 2 3.y 
gm $polyl] 
( 2 


= 0; 
= 180; 
= -40; 
= 200; 
Lne_2dl6 


. P 


. FALSE 


. stal 
); 


:us 
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p[ 1 ] .X := 12; 
p[ 2 ] .X := 52; 
gm_$polyline_2dl6 
( 2 

' P 

. FPdJSE 
, YPCUSE 
. status 
); 
check; 



p[ 1 ] .X ;= 4; 

p[ 1 ] .y := 190; 

p[ 2 ] .X := -20; 

p[ 2 ] .y := 230; 
gin_$polyline_2dl6 

( 2 

' P 

. Status 
); 
check; 



p[ 1 ] .X := 8; 
p[ 1 ] .y := 190; 
p[ 2 ] .X := 32; 
pC 2 ] .y := 230; 
gm_$polyline_2dl6 
( 2 

' P 

. FALSE 
. FALSE 
, Status 
); 
check; 



p[ 1 ] .X := 6; 
p[ 1 ].y := 195; 
p[ 2 ] .X := 6; 
p[ 2 ] .y := 240; 
gm_$polyline_2dl6 
( 2 

• P 

. FALSE 
. FALSE 
, Status 
); 
check; 



p[ 1 ] .X := 0; 
p[ 1 ] .y := 170; 
p[ 2 3 .X := 0; 
pC 2 3 .y := 150; 
gm_$polyline_2dl6 
( 2 

' P 

. FALSE 

, FALSE 
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status 



); 
check; 



p[ 
P[ 



= 12; 
= 12; 



gm_$polyline_2dl6 



( 



2 

P 

FALSE 
FALSE 
status 



check; 

gm_$segment_close 

( TRUE 

. status 

); 
check; 

gin_$segment_create 

C " 
. 

, sid_scene 
, status 
); 
check; 

p[ 1 ] .X := 0; 
p[ 1 ].y := 0; 
gm_$instance_translate_2dl6 

( sid_house 

, p[ 1 3 

, status 

); 
check; 

p[ 1 ] .X := -85; 

p[ 1 3 .y := -25; 
gm_$instance_scale_2dl6 

( sid_tree 

, 2.0 

, p[ 1 3 

. status 

); 

p [ 1 3.x : = 530 ; 

p[ 1 3 .y := 55; 

gm_$instance_scale_2dl6 

( sid_tree 

. 0.75 

. pC 1 3 
, status 
); 
check; 

p[ 1 3 x := 610; 



< Create the segment called "scene." > 



< Instance the segment for the house . > 



< Instance, translate, and scale } 

< the segment for the trees . > 
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p[ 1 ] .y := 105; 
gm_$instance_scale_2dl6 

( sid_tree 

, 0.85 

. pC 1 ] 
. status 
); 
check; 

gm_$segment_close 

( TRUE 

. status 

); 
check; 

gm_$display_segment < Now display the completed scene . > 

( sid_scene 

. status 

); 
check; 

pause. 10W32 := f ive_seconds; < Admire the scene for five seconds. > 

pause. highie := 0; 

TIME_$WAIT 

( time_$relative 

, pause 

, status 

); 
check; 

gm_$file_close < Close and save the file. > 

( TRUE 
, status 

); 
check; 

gm_$terminate ■( Terminate the 2D GMR package . > 

( status 

); 
check; 

END. 
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Appendix E 
C Program Examples 



This Appendix contains the programming examples presented in the manual translated into C. 

A Program to Draw a Rectrangle 

The following program demonstrates how to initialize the 2D GMR package, create a metafile, 
create a segment, and draw a rectangle (see Section 3.8 and Figure 3-3). 

/* PROGRAM draw_rectangle */ 



#nolist 

#include <stdio.h> 

#include "/sys/ins/base . ins.c" 

#include "/sys/ins/gmr . ins .c" 

#include "/sys/ins/tlme . ins .c" 

#llst 

#define one_second 250000 

#define five_seconds (5 * one_second) 

#define ten_seconds (10 * one_second) 

short file_id; 

gm_$segment_id_t segment_id; /* 4-byte integer */ 

status_$t St; 

gm_$pointi6__t ptl, pt2; /* array of two 2-byte integers */ 

long i; 

gm_$pointl6_t bitmap_size = ■Cl024,1024>; 

time_$clock_t pause; 

mainO 
i 

/* Define the coordinates of the rectangle to be drawn. */ 
ptl .X = 100; 



ptl 
pt2 
pt2 



y = 30; 
X = 200; 
y = 50; 



/* Initialize 2D GMR. */ 

gin_$init( g!n_$direct, 
(short) 1. 
bitmap_size, 
(short) 8, 
St) ; 

/* Create and name a metafile. */ 

gm_$f lle_create("gmf ile" . 
(short) 6, 
gm_$overwrite, 
gm_$lw. 
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file_id, 
St); 

/* Create and name a segment . */ 

gm_$segment_create("rectang_seg" . 

strlen("rectang_seg") . 

segment_id, 

st) ; 

/* Insert tlie rectangle */ 

gm_$rectangle_16( ptl, 

pt2. 

false, 

st) : 

/* Display the file. */ 

gm_$dlsplay_f ile(st) ; 

/* Keep the figure displayed on the screen for five seconds.*/ 
pause . lo¥32 = f ive_seconds; 
pause. highie = 0; 
tlme_$¥ait( time_$relative, 
pause, 
st ) ; 

/* Close the segment.*/ 

gm_$segm6nt_close (true . 
st) ; 

/* Close the metafile. */ 
gm_$f ile_close( true, 
st) ; 

gm_$terminate(st) ; 

} 
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A Program Using Primitives and Instancing 

The following program draws the design in Figure 4-2 using primitives and instancing (see 
Section 4.6). 



/* PROGRAM fo\ir_rec */ 

#nolist 

#incliide <stdio.li> 

#include " /sys/lns/base . ins . c " 

#include "/sys/ins/gmr . ins .c" 

#include " /sys/ins/t ime . ins . c " 

#list 

#deflne one_second 250000 

#define five_seconds ( 5 * one_second) 

#define ten_seconds (10 * one_second) 

short file_id; 

gm_$segment_id_t small_id: /* 4-byte integer */ 

gm_$segment_id_t large_id; 

status_$t st; 

gm_$pointl6_t ptl. pt2; /* array of two 2-byte integers */ 

long i; 

gm_$pointl6_t bitmap_size = -(1024, i024>; 

gm_$pointl6_t position; /* array of two 2-byte integers */ 

gm_$point_arrayl6_t positions; 

gm_$dra¥_pattern_t pattern; 

time_$clock_t pause; 

mainO 
i 

/* Initialize 2D GMR. */ 
gm_$init( gm_$direct, 
(short) 1. 
bitmap_size, 
(short) 8, 
St) ; 

/*Create and name a metafile.*/ 

gm_$f ile_create("gmf ile" , 
(short) 6, 
gm_$over write. 
gm_$lw. 
file_id. 
St) ; 

/* Create and name a segment . */ 

gm_$segment_create("small_rec" , 

(short) strlen("small_rec") , 

small_id, 

St) ; 
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/* Define the coordinates of the rectangle . */ 
ptl .X = 100; 
ptl.y = 100; 
pt2.x = 200; 
pt2.y = 200; 

/* Draw one small rectangle . */ 

gm_$rectangle_16( ptl. 
pt2, 
true. 
St); 

/* Close the segment. */ 

gm_$segment_close ( true. 
St); 

gm_$segment_create("large_rec''. 

(short) s tr len ( " large_rec " ) 

large_i(i. 

st); 

/* Define the coordinates of the rectangle . */ 
ptl.x = 100; 
ptl.y = 100; 
pt2.x = 600; 
pt2.y = 600; 

/* Draw a rectangle . */ 
gm_$rectangle_16( ptl. 
pt2. 
false. 
St) ; 

/* Instance the small rectangle four times . */ 
position. X = 100; 
position. y = 100; 

gm_$instance_translate_2dl6 ( small_id. 

position. 
St) ; 

position. X = 300; 
position. y = 300; 

gm_$instance_trans],ate_2dl6 ( small_id. 

position, 
st) ; 

position. X = 300; 
position. y = 100; 

gm_$instance_translate_2dl6( small_id. 

position, 
st) ; 

position. X = 100; 
position. y = 300; 
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gin_$instance_translate_2cil6 ( small_id, 

position, 
St) ; 

/* Draw two polylines connecting four rectangles. */ 
positions [0] .x = 300; 
positions [0] .y = 300; 
positions [1] .x = 400; 
positions [1] .y = 400; 
gm_$polyline_2dl6 (2, positions , false . false . st) ; 

positions [0] .x = 300; 
positions [0] .y = 400; 
positions [1] .x = 400; 
positions [1] .y = 300; 

gm_$polyline_2(il6( (short) 2, 
positions, 
false, 
false, 
St) ; 

/* Close the segment. */ 

gm_$segment_close( true, 
St); 

gm_$display_segment( large_id, 

St) ; 

/* Keep figure displayed on the screen for five seconds. */ 
pause . low32 = f ive_seconds; 
pause. highie = 0; 

time_$wait( time_$relative, 
pause, 
St ) ; 

/* Close the metafile. */ 
gm_$f ile_close( true, 
St) ; 

/* Terminate 2D GMR. */ 

gm_$terminate(st) ; 
> 
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A Program with Attributes and Instancing 

The following program modifies the program above by adding an attribute command (see Section 
5.4). 

/* PROGRAM draw_rectangles */ 

#nolist 

#include <stdio.h> 

#include "/sys/ins/base . ins . c" 

#include "/sys/lns/gmr . ins .c" 

#include "/sys/ins/time . ins . c" 

#list 

#deflne one_second 250000 

#define five_seconds (5 * one_second) 

#define ten_seconds (10 * one_second) 

short file_id; 

gm_$segment_id_t small_id; /* 4-byte integer */ 

gm_$segment_id_t large_id; 

status_$t St; 

gm_$pointl6_t ptl, pt2; /* array of two 2-byte integers */ 

long i ; 

gni_$pointi6_t bitmap_slze = -[1024, 1024>; 

gm_$pointl6_t position; /*array of two 2-byte integers */ 

gm_$point_arrayl6_t positions; 

gin_$dra¥_pattern_t pattern = {'\377', '\360'>; 

time_$cloc)c_t pause; 

mainO 

i 

/* Initialize 2D GMR. */ 

gm_$init( gin_$direct, 
(short) 1, 
bitmap_size, 
(short) 8, 
St) ; 
/* Create and name a metafile . */ 

gm_$file_create("gmfile" , 
(short) 6, 
gm_$over write, 
gm_$lw, 
file_id,st) ; 

/* Create and name a segment . */ 

gm_$segment_create("small_rec" , 

(short) strlen("small_rec") . 

small_id, 

st); 

gm_$draw_style(gm_$dotted. 
(short)4, 
pattern, 
(short)O, 
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St); 

/* Define the coordinates of the rectangle. */ 
ptl.x = 100; 
ptl .y = 100; 
pt2.x = 200; 
pt2.y = 200; 

/*Draw one small rectangle.*/ 
gm_$rectangle_16( ptl, 
pt2, 
false, 
St) ; 

/* Close the segment. */ 

gm_$segment_close (true . st) ; 

gm_$segment_create("large_rec" . 

(short) strlen("large_rec") 
large_id, st) ; 

/* Instance the small rectangle four times. */ 
position. X = 100; 
position./ = 100; 

gm_$instance_translate_2dl6 ( small_id, 

position, 
st) ; 

position. X = 300; 
position. y = 300; 

gm_$instance_translate_2dl6( small_id, 

position, 
st) ; 

position. X = 300; 
position. y = 100; 

gm_$instance_translate_2dl6 ( small_id, 

position, 
st) ; 

position. X = 100; 
position. y = 300; 

gm_$instance_translate_2dl6 ( small_id, 

position, 
st); 

gm_$draw_style( gm_$patterned, 
(short) 1, 
pattern, 
(short) 16, 
st); 

/* Define the coordinates of the rectangle. */ 
ptl.x = 100; 
ptl.y = 100; 



E-7 C Program Examples 



pt2.X = 600; 
pt2.y = 600; 

/* Draw a rectangle . */ 

gm_$rectangle_16( ptl, 
pt2. 
false, 
St) : 

/* Draw two polylines connecting four rectangles . */ 
positions [0] .x = 300; 
positions [0] .y = 300; 
positions [1] .x = 400; 
positions [1] .y = 400; 

gm_$polyline_2dl6( (short) 2, 
positions, 
false, 
false, 
St) ; 

positions [0] .x = 300; 
positions [0] .y = 400; 
positions [1] .x = 400; 
positions [1] .y = 300; 

gm_$polyline_2<il6( (short) 2, 
positions, 
false, 

X ctXSQ , 

St); 

/* Close the segment. */ 

gm_$segment_close ( true, 
St) ; 

gm_$<iisplay_segment( large_id, 

St); 

/* Keep figure displayed on the screen for five seconds. */ 
pause . low32 = f ive_seconds; 
pause. highie = 0; 

time_$wait( time_$relative, 
pause, 
St ); 

/* Close the metafile. */ 

gm_$f ile_close( true, 
St) ; 

/* Terminate 2D GMR. */ 

gm_$terminate(st) ; 
> 



C Program Examples E-8 



A Ptogram Including Text 

The following program draws the design in Figure 6-1. This is a rectangle with horizontal and 
vertical text strings (see Section 6.5). 

/* PROGRAM draw_rectangle_text */ 

#nolist 

#lnclude <stciio.h> 

#include "/sys/ins/base .ins .c" 

#lnclude "/sys/ins/gmr . ins .c" 

#include "/sys/ins/time . ins.c" 

#list 

#define one_second 250000 

#define five_seconds (5 * one_second) 

short file_id; 

gm_$segment_ld_t segment_id; /* 4-byte integer */ 

status_$t St; 

gm_$pointl6_t ptl, pt2. point; /* array of two 2-t)yte integers */ 

long i ; 

gm_$pointl6_t bitmap_si2e = -(1024. 1024>; 

short ffid; 

time_$clock_t pause; 

mainO 

/^Initialize 2D GMR.*/ 

gm_$init( gm_$direct, 
(short) 1, 
l)itmap_size, 
(short) 8, 
St) ; 
/* Create and name a metafile. */ 

gm_$file_create("gmfile", 
(short) 6, 
gm_$overwrite. 
gm_$lw, 
file_id. 
St); 

/* Create and name a segment. */ 

gm_$segment_create("rectang_seg". 

(short) strlen("rectang_seg") . 

segment_id, 

St); 

/*Load the font family.*/ 

gm_$font_f amily_include( "f ont_f amilies" . 

(short) strlen("font_families") , 

gm_$pixel. 

ffid, 

St ) ; 
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gm_$text_size( (float) 14.0, 

St): 
point. X = 5; 
point. y = 510; 

gm_$text_2dl6 ( point, 

(float) 0.0 , 

"This is the top of the rectangle." , 

(short) strlen("This is the top of the rectangle."), 

St ); 

point. X = 5; 
point. y = 50; 

gm_$text_2dl6 ( point, 

(float)-90.0, 

"This is the side of the rectangle.", 

(short) strlen("This is the side of the rectangle.") 

St ) ; 

/* Define the coordinates of the rectangle to be drawn. */ 
ptl.x = 10; 
ptl .y = 30; 
pt2.x = 400; 
pt2.y = 500; 

gm_$rectangle_16( ptl, 
pt2, 
false, 
St); 

/*Close the segment.*/ 

gm_$segment_close ( true, 
St) ; 



/* Display the file. */ 

gm_$display_file(st) ; 

/* Keep figure displayed on the screen for five seconds . */ 
pause. low32 = f ive_seconds; 
pause .highie = 0; 

time_$wait( time_$relative, 
pause, 
St ) ; 

/* Close the metafile. */ 

gm_$file_close( true, 
St); 

gm_$terminate(st) ; 
> 
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A Program With Stroke and Pixel Fonts 

The following program loads a pixel font family file and a stroke font family file and then shifts 
back and forth between them using an attribute block and attribute class command (see Section 
6.9). The purpose of this program is to illustrate the use of the two types of text. The attribute 
block and attribute class command provide an easy way to change text size. For a discussion of 
attribute blocks and attribute classes, see Chapter 13. 

/* PROGRAM text */ 

#nolist 

#include <stclio.h> 

#include <matli.h> 

#include "/sys/ins/base .ins .c" 

#include " /sys/ins/gmr . ins . c " 

#include "/sys/ins/pfm. ins .c" 

#include " /sys/ins/t ime . ins . c '• 

#llst 



#define aclassl 
#define second 
#define cos_delta 
#define sin delta 



500000 

(float) cos ( 0.25 ) 

(float)sin( 0.25 ) 



status_$t 

gm_$segment_id_t 

gm_$segment_id_t 

short 

short 

short 

short 

gm_$pointl6_t 

gin_$pointl6_t 

gm_$boundsreal_t 

short 

short 

float 

float 

gm_$rotate_real2x2_t 

gm_$pointl6_t 

time $clock t 



status; 

sid_text; 

sid_top; 

file_id; 

ff id_pixel; 

ffid_stroK:e; 

ablock_id; 

dbounds ; 

i; 

j: 

text_size; 

text_size_delta; 

rotate; 

translate; 



pause; 
mainO 

p.X = 1024: 

p.y = 1024; 



/* Initialize the 2D GMR package. */ 

gm_$init( gm_$direct, 
(short) 1. 

P' 

(short) 8, 
status) ; 
check (status) ; 

/* Create and name a metafile. */ 
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gm_$file_create( "gmfile", 
(short) 6. 



gm_$overwr ite , 
gm_$lw, 
file_id, 
status) ; 



check ( status ) ; 



/* Set the viewport refresh state . */ 

gm_$viewport_set_refresh_state ( gm_$ref resh_wait, 

status) ; 

check (status) : 

/* Include a pixel font family. */ 
gm_$f ont_f amily_include ( "f f 0" , 

(short) 3, 
gm_$plxel, 
ffid_pixel, 
status) ; 
" check (status) ; 

/* Include a stroke font family. */ 
gm_$font_family_include( "ffsV 

(short) 3, 
gm_$stroke. 
f f id_stroke, 
status) ; 

check ( status ) ; 

/* Create an ablock. */ 

gm_$ablock_create ( (short) 1 , 
al)lock_id, 
status) ; 

check (status) ; 

/* Set the ablock_id = aclassl. . */ 

gm_$ablock_assign_display ( aclassl , 

ablock_id, 
status) ; 

check (status) : 

/* Create a text segment. */ 

gm_$segment_create ( (char *)NULL. 

(short) 0, 
sid_text, 
status) : 

check (status) ; 

/* Add an aclass command. */ 
gm_$aclass( aclassl. 
status) ; 

check ( status ) ; 
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p.x = - 5; 

p.y = - 5; 

q.x = 5; 

qy = 5; 

/* Add a unfilled rectangle. */ 

gm_$rectangle_16( p, 

q- 

false, 
status) ; 
check (status) ; 

p.x = 10; 
py = 0; 

/* Add Left to Right text. */ 

gm_$text_2dl6( p, 

(float)O.O, 
"Left to Right", 
(short) 13, 
status) ; 

check ( status ) ; 

p.x = 0; 
p.y = - 10; 

/* Add Top to Bottom text. */ 

gm_$text_2dl6( p, 

(float) 90.0, 
"Top to Bottom", 
(short) 13, 
status) ; 

check(status) ; 

p.x = - 10; 
p.y = 0; 

/* Add Right to Left text. */ 

gm_$text_2dl6( p, 

(float) 180.0, 
"Right to Left", 
(short) 13, 
status) ; 

check ( status ) ; 

p.x = 0; 
p.y = 10; 

/* Add Bottom to Top text. */ 

gm_$text_2dl6( p, 

(float) -90.0, 
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"Bottom to Top" , 

(short) 13, 
status) ; 



check ( status ) ; 



/* Close the segment. */ 

gm_$segment_close ( true . 

status) ; 

check (status) ; 

dbounds . xmin = - 50 . ; 
dbounds . ymin = - 50.0; 
dbounds . xmax = 50 . ; 
dbounds . ymax = 50 . ; 

pause . low32 = second / 4; 
pause .highie = 0; 

text_size = 10.0: 
text_size_delta = 1.0; 

/* * * Illustrate different text sizes with pixel and stroke text. * * */ 

for(j=0; j<2; j++) 

if(j == 1) 

/* Set ablock to pixel font family. */ 

gm_$ablock_set_font_family(.ablock_id, 

ff id_pixel, 
status) ; 

else 

/* Set ablock to stroke font family. */ 

gm_$ablock_set_font_family( ablock_id, 

ff id_stroke, 
status) ; 

check(status) ; 

for(i=0; i<20; i++) 
■C 

if( text_size >= 10.0) 

text_size_delta = - (fabs( (double) text_size_delta )); 
else 

if (text_size <= fabs( (double) text_size_delta )) 

text_size_delta = fabs( (double) text_size_delta ); 

text size += text size delta; 



/* Change ablock text size. */ 
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gm_$ablock_set_text_size( ablock_id. 

text_size, 
status) : 

check ( status ) ; 

/* Display the file. */ 

gm_$display_file_part( dbounds, 

status) ; 

check ( status ) : 

/* Admire it for a momemt. */ 

time_$wait( time_$relative, 
pause, 
status) : 

check ( status ) ; 
>/* end for i */ 
>/* end for j*/ 

/* Create top segment. */ 

gm_$segment_create ( (char *)NULL. 

(short) 0, 
sid_top, 
status) ; 

check ( status ) ; 

/* Identity matrix */ 
rotate. XX = 1.0; 
rotate . xy = 0.0; 
rotate .yx = 0.0; 
rotate .yy = 1.0; 

/* Zero translation */ 
translate. X = 0; 
translate .y = 0; 

/* Instance text segment into top segment. */ 

gm_$instance_transform_2dl6( sid_text. 

rotate, 
translate, 
status) ; 

check ( status ) ; 

/* Go into replace mode . */ 

gm_$modelcmd_set_mode ( gm_$modelcmd_replace , 

status) ; 

check ( status ) ; 

/* * * Illustrate different text angles with pixel and stroke text. * * */ 

for(j=0; j<2; j++) 
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lf( j == 1) 

/* Set ablock to pixel font family. */ 

gm_$ablock_set_font_family( ablock_id, 

ffid_pixel, 
status) ; 
else 

/* Set ablock to stroke font family. */ 

gm_$ablock_set_font_family( ablock_l(i, 

ffi(i_stroke, 
status) ; 

check ( status ) ; 

for(i=0; i<40: i++) 
{ 

/* Increment rotation matrix. */ 

rotate. XX = cos_delta * rotate. xx + sin_delta * rotate. xy; 
rotate. yx = cos_delta * rotate. yx + sin_delta * rotate. yy; 
rotate. xy = -rotate. yx; 
rotate. yy = rotate.xx; 

/* Change the angle of the instance transform. */ 

gm_$instance_transf orm_2dl6 ( sid_text . 

rotate, 
translate, 
status) ; 

check ( status ) ; 

/* Display the file. */ 

gm_$display_f ile_part( dbounds. 

status) ; 

check ( status ) ; 

/* Admire it for a moment. */ 

time_$wait( time_$relative, 
pause, 
status) ; 

checkC status ) ; 

>/*end for i */ 
>/* end for j */ 

/* Close the top segment. */ 

gm_$segment_close ( true. 

status) ; 
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check (status) ; 

/* Close the file. */ 

gm_$file_close( true, 

status) ; 

check ( status ) ; 



/* Terminate the 2D GMR package . */ 

gm_$termlnate (status) ; 

check ( status ) ; 
> 

check (status) 

status_$t status; 
i 

if (status. all != status_$ok) 
pfm_$error_trap (status) ; 

> 
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Program to Change the View 

This program opens and displays an existing file and then changes the view scale to shrink the 
viewport. (For an existing file, you may use the program called "hotel" in Appendix D . As 
viewports may not overlap, this makes room for a second viewport. The second viewport is 
created, and the file is displayed in it. The view scale is then changed for the second viewport 
(see Section 8.9). 

/* PROGRAM coures2 */ 



#nolist 

#include <stdio.h> 

#include "/sys/ins/base . ins .c" 

#include "/sys/ins/gmr . ins . c" 

#list 



status $t 


status; 


name $pname t 


name; 


short 
short 
short 
short 


length; 
vpid2; 
vpidS; 
file_id; 


gm_$pointreal_t 
gm_$boundsreal t 
gm_$pointl6 t 
short 


rtransl; 
b; 

bitmap_size 
1; 


mainO 




printf("File name: \n") ; 

gets (name) ; 

length = strlen(name) ; 



bitmap_size .X = 1024; 
bitmap_size .y = 1024; 

gm_$init( gm_$dlrect. 

stream_$stdout . 
bitmap_size, 
(short) 8. 
status) ; 

gm_$f ile_open( name, 

length, 
gm_$r , 
gm_$l¥, 
file_id, 
status ) ; 

/* Now display the file. */ 

gm_$display_file (status) ; 

/* Change the view scale . */ 
rtransl. X =0.0; 
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rtransl.y = 1.0; 

gm_$vie¥_scale( (float) 0.25, 
rtransl, 
status) ; 

forCi=0; KIO; i++) 

gm_$view_scale( (float) 1.05. 
rtransl, 
status) ; 

rtransl .x = 0.1; 
rtransl .y = 0.8; 
for(l=0; KIO; i++) 

gm_$vie¥_scale ( (float) 0.92, 
rtransl, 
status) ; 

/* Shrink the viewport. */ 
b . xmin =0.0; 
b.ymin =0.6; 
b . xmax = . 38 ; 
b . ymax = 1.0; 

gm_$viewport_set_bouncis ( b , 

status) ; 

/* Create a second viewport . */ 
b.xmin =0.4; 
b.ymin =0.0; 
b . xmax = 1.0; 
b . ymax =0.6; 

gm_$viewport_create ( b, 

vpid2, 
status) ; 

/* Display file in second viewport. */ 
gm_$display_file (status) ; 

/* Change view scale in second viewport. */ 
rtransl. X =0.7; 
rtransl .y = 0.3; 
for(i=0; i<10; i++) 

gm_$view_scale( (float) 1.05, 
rtransl, 
status) ; 

for(i=0; i<3; i++) 

gm_$vie¥_scale( (float) 0.85, 
rtransl, 
status) ; 

/* Switch back to first viewport. */ 

gm_$viewport_select( (short) 1, 

status) ; 
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rtransl.x = 0.0; 
rtransl.y =0.9; 
for(i=0; KIO; i++) 

gm_$view_scale ( (short) 1 . 05 , 
rtransl. 
status ) ; 

for (1=0; i<3; i++) 

gm_$view_scale ( (float) 0.9. 
rtransl, 
status ) ; 

/* Switch back to second viewport. */ 
gm_$viewport_select( vpid2., 

status) ; 

/* Translate the (second) viewport. */ 
rtransl.x = 0.0; 
rtransl.y = -0.4; 

gm_$vie¥_translate( rtransl. 
status) ; 

/* Shrink the second viewport. */ 
b.xmin =0.4; 
b.ymin =0.4; 
b . xmax = 1.0; 
b . ymax = 1.0; 

gm_$vlewport_set_bounds( b, 

status) ; 

/* Create a third viewport. */ 
b.xmin =0.0; 
b.ymin =0.0; 
b . xmax = 1.0; 
b.ymax =0.2; 

gm_$vlewport_create ( b . 

vpid3. 
status) ; 

/* Display file in third viewport. */ 
gm_$display_f lie (status) ; 

gm_$vlewport_inq_bounds ( b . 

status) ; 

/* Change view scale in third viewport . */ 
rtransl .x = 0.9; 
rtransl.y =0.1; 
for (1=0; K20; 1++) 

gm_$view_scale ( (float) 0.9, 
rtransl. 
status) ; 

/* Close the file. */ 

gm_$file_close( true. 
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status) ; 
gm_$terminate (status) ; 
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An Interactive Program 

The following program creates one segment containing sixteen filled polyline commands. The 
user can then pick and move the commands and demonstrate three model command modes (see 
Section 9.3). 

/* PROGRAM star_move */ 

/* The following keys are enabled and perform the following actions: */ 

/* */ 

/* P Toggle to pick/replace a command */ 

/* Q Quit */ 

/* ""X Abort rubberbanding (command is NOT replaced) */ 



#nolist 

#include <stdio.h> 

#include <math.h> 

#lnclude "/sys/ins/base . ins .c" 

#include "/sys/ins/error . ins . c" 

#lnclude "/sys/ins/gmr . ins .c" 

#lnclude "/sys/ins/pfm. ins . c" 

#list 



#define SETSIZE 


(short) 256 




#define ctrlx 


'\030' 




#define stars_x 


4 




#define stars y 


4 




gm_$event t 


ev type; 




char 


character: 




gm_$pointreal_t 


bitmap_pos; 




short 


viewport id; 




gm_$polntreal_t 


segment_pos; 




status_$t 


status; 




gm_$event_t 


flush ev_type; 




char 


flush character; 




gm $pointreal t 


flush bitmap pos; 




short 


flush viewport id; 




gm_$pointreal_t 


flush segment pos; 




status_$t 


f lush_status; 




short 


i; 




short 


j: 




short 


k; 




gm_$point_arrayl6_t 


star; 




short 


vertices; 




boolean 


closed; 




boolean 


filled; 




gm_$pointreal_t 


last segment pos; 




gm $pointl6_t 


delta; 




short 


file_id; 




gm_$segment_id_t 


Sid; 




long 


n instances; 




gm_$boundsreal_t 


bounds; 




boolean 


command_picked; 




gm $pointi6_t 


bitmap_size = -C 1024, 


1024 > 
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gin_$pointreal_t piclc_aperture = < 4.0, 4.0 >; 

gm_$keyset_t keyset; 

Check (status) 

status_$t status; 
i 

if (status .all != status_$ok) 
pfni_$error_trap (status) ; 
} 

malnO 
■C 

/* Initialize the 2D GMR package . */ 
gin_$init( gm_$direct, 

(short) 1, 

bitmap_size, 

(short) 8, 

status) ; 

check (status) ; 

/* Create a file named "stars. gmr". */ 
gin_$f ile_create( "stars .gmr" , 

(short) strlen(" stars .gmr") , 

gm_$over write, 

gm_$lw, 

f ile_id, 

status) ; 

check(status) ; 



/* Coerce REAL data to INTEGER32 . */ 
gm_$data_coerce_set_real ( gm_$32. 

status) 

check(status) ; 

/* Create an unnamed segment . */ 

gm_$segment_create( (char *)NULL, 

(short) 0, 
Sid, 
status) ; 

check(status) ; 



/* Define a filled polyline. */ 
starCO] .X = 000; 



star[0] 
star [1] 
star [1] 
star [2] 
star [2] 
star [3] 
star [3] 
star [4] 
star [4] 



y = 000 
X = 400 
y = 300 
X = 000 
y = 300 
X = 400 
y = 000 
X = 200 
y = 400; 
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closed = true; 
filled = true: 
vertices = 5; 

/* Set model command mode to INSERT. */ 

gm_$modelcmd_set_mode ( gm_$modelcmd_insert , 

status) ; 

check (status) ; 

/* Insert polylines into the segment. */ 
for(i=0; i<stars_x; i++) 
< 

for(j=0; j<stars_y; j++) 
■C 

gm_$polyline_2dl6( vertices, 
star, 
closed, 
filled, 
status) ; 

check (status) ; 

for(k=0; k < vertices; k++) 

star[k] .y = starCk] .y -«- 600; 
}/* end for j */ 
for(k =0; k < vertices; k++) 
{ 

star[k] .X = star[lc] .x + 600; 
star[k] .y = star[k] .y - 600 * stars_y; 
>/* end for k */ 
>/* end for i */ 

/* Display the segment. */ 
gm_$display_segment( sid, 

status) ; 

check (status) ; 

/* Set the refresh state to partial. */ 

gm_$vie¥port_set_ref resh_state ( gm_$ref resh_partial , 

status) ; 

check (status) ; 

/* Make the cursor active . */ 
gm_$cursor_set_active ( true, 

status) ; 

check (status) ; 

/* Enable keys ""X, P, and Q. */ 

lib_$init_set (keyset, SETSIZE) ; 

lib_$add_to_set (keyset, SETSIZE, ctrlx) ; 

lib_$add_to_set (keyset, SETSIZE, 'P'); 

lib_$add_to_set (keyset, SEITSIZE, 'Q'): 

lib_$add_to_set (keyset, SEITSIZE. 'p'); 



C Program Examples E-24 



lib_$add_to_set (keyset, SETSIZE, 'q'); 

gin_$input_enable( gm_$key stroke, 
keyset, 
status) ; 

check (status) ; 

/* Enable locator events . */ 

gm_$lnput_enable( gm_$locator, 
OL, 
status) ; 

check (status) ; 

command_picked = false; 

do 
i 
/* Walt for an event. */ 

gm_$input_event_wait( true, 

ev_type , 

character, 

bltmap_pos, 

viewport_id, 

segment_pos, 

status) ; 

check (status) ; 

if(ev_type == gm_$locator) 
do 
i 
/* Flush the queue . */ 

gm_$input_event_walt( false, 

f lush_ev_type , 
flush_character, 
f lush_bltmap_pos , 
flush_viewport_id, 
f lush_segment_pos , 
f lush_status) ; 

if (flush_ev_type != gm_$no_event) 
i 

®^_^yP® ~ flush_ev_type; 

character = flush_character; 

bitmap_pos = flush_bitmap_posj 

viewport_id = flush_viewport_ld: 

segment_pos = flush_segment_pos; 

status = flush_status; 

check (status) ; 
>/* end if */ 
>while(f lush_ev_type == gm_$locator) ;/* end do */ 



/* Do case event type . */ 

switch (ev_type) 
■C 
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case gm_$keystroke : 

switch (character) 
i 

case 'P' : 
case 'p' : 

if ( ! comman(i_picked) 

i 

/* Set the pick center. */ 

gm_$pick_set_ceiiter ( segment_pos , 

status) ; 

check(status) ; 

/* Set the pick aperture . */ 

gin_$pick_set_size ( pick_aperture , 
status) ; 

check(status) ; 

/* Clear old pick list. */ 

gin_$pick_segment( gin_$clear. 

Sid, 

ii_instances, 

bounds, 

status) ; 
check (status) ; 

/* Setup pick at top segment. */ 

gm_$pick__segment( gin_$setup, 

Sid. 

n_instances. 

bounds , 

status) : 
if( status. all == status_$ok) 
i 

/* Initialize pick_command . */ 

gm_$pick_command( gm_$start, 

status) J 
check (status) ; 

/* Pick a command. */ 

gm_$pick_command( gm_$cnext. 
status) ; 

command_picked = (status. all == status_$ok) 
>/* end if */ 

if (command_picked) 
i 

/* Highlight the picked command. */ 

gm_$pick_highlight_command( gm_$outline, 

(float) 1 .0, 
status) ; 
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check (status) ; 
/* Inquire about tlie picked polyline. */ 



gm_$lnq_polyllne_2(il6( vertices, 

star, 
closed, 
filled, 
status) ; 

check (status) ; 



/* Change to rubberband mode . */ 



gm_$modelcmd_set_mode ( giii_$modelcmd_rubberband, 

status) ; 



check(status) 
/* Turn off the cursor . */ 



gin_$cursor_set_active ( false, 

status) ; 

check (status) ; 

last_segment_pos = segment_pos: 
>/* end If */ 
>/* end if ( !command_picked) */ 
else 
i 



/* Change to replace mode . */ 



gm_$modelcmd_set_mode ( gm_$modelcmd_replace , 

status) ; 



check (status) ; 
/* Replace the polyline. */ 



gm_$polyllne_2dl6( vertices, 
star, 
closed, 
filled, 
status) ; 



check(status) ; 
/* Turn the cursor on. */ 



gm_$cursor_set_actlve( true, 

status) ; 

check(status) ; 

command_picked = false; 
>/* end else */ 
break; 

case ctrlx: 

command_plcked = false; 
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/* Turn off rubberband mode . */ 



gm_$modelcmd_set_inode ( gin_$modelcmd_replace , 

status) : 



clieck (status) ; 
/* Turn the cursor on. */ 



gm_$cursor_set_actlve ( true, 

status) ; 

clieck (status) ; 
break; 

case 'q' : 

/* Quit. */ close ; 

exit(O); 
break: 
>/* end switch character */ 

case gm_$ locator : 

if (command_picked) 

delta. X = (short) floor ( (double) ( segment_pos . x - last_segment_pos .x + 0.5 )), 
delta. y = (short) floor ( (double) ( segment_pos.y - last_segment_pos.y + 0.5)), 
last_segment_pos = segment_pos; 

for(i=0; i < vertices; i++) 

< 

star[i ] .X = star[i].x + delta. x; 

star[i].y = star[i].y + delta. y; 

>/* end for */ 

/* Move XOR-rubberband . */ 

gm_$polyline_2di6 ( vertices, 
star, 
closed, 
filled, 
status) ; 

check (status) ; 
>/* end if */ 

else 
< 

gm_$cursor_set_position ( bitmap_pos . 

status ) ; 
check (status) ; 
>/* end else */ 
break; 
>/* end switch */ 
>while(true) ;/* end do */ 
>/* end mainO */ 

close 
•C 
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/* Close the segment. */ 

gm_$segment_close ( true, 

status) ; 

check(status) ; 

/* Close the file. */ 

gm_$f ile_close( true, 

status) ; 

checkCstatus) ; 

/* Terminate the session. */ 

gm_$terminate (status) ; 

CheckCstatus) ; 
>/* end close */ 
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A Program with Attribute Classes and Blocks 

The following program creates a hierarchy of segments including instance commands. It displays 
the file in three viewports; adds attribute class commands to the file; assigns attribute blocks to 
attribute classes; displays the segments; closes the file; and terminates the package (see Section 
13.11). 

/* attributes */ 

/* PROGRAM courses */ 

#nolist 

#inclu<ie <stdio.h> 

#include "/sys/ins/base . ins .c" 

#inclucie "/sys/ins/time . ins .c" 

#include "/sys/ins/gmr . ins . c" 

#list 

#define aclassidl 1 

#define aclassid2 2 

#define vpidl 1 

#define one_second 250000 

gm_$pointl6_t bitmap_size = {1024,1024>; 

status_$t st; 

gin_$boundsreal_t bj 

short vpid2,vpid3; 

short file_id; 

gm_$segment_id_t sidl, sid2.sid3; 

short ablockidl,ablockid2,ablock:id3; 

short ablockid4,ablockid5.ablockid6: 

gm_$pointl6_t ptl,pt2; 

short lint; 

gin_$dra¥__pattern_t pattern; /* bit pattern */ 

time_$clock_t pause; 

mainO 
< 

gm_$initC gm_$borro¥, 

(short) 1, 

bitmap_size, 

(short) 8, 

St) ; 

/* Create three viewports. */ 
b.xmin =0.0; 
b.ymin = 0.0; 
b.xmax = 0.49; 
b.ymax = 0.49; 

gm_$viewport_set_bounds( b, 

St) ; 

b .xmin = .51; 
b.ymin = 0.0; 
b . xmax = 1.0; 
b.ymax = 0.49; 



G Program Examples E-30 



gin_$viewport_create( b, 

vpid2, 
St) ; 

to . xmin =0.0; 
b.ymln = 0.51; 
b . xmax = 1.0; 
b . ymax = 1.0; 

gm_$viewport_create ( b. 

vpidS, 
St); 

/* Display segments . */ 

gm_$f ile_create("gmfile" , 
(short) 6, 
giii_$over write, 
gin_$lw. 
file_id, 
St) ; 

gm_$segment_create ("bottom" . 

(short) 6, 
sidl, 
St) ; 

ptl .X = 0; 
ptl .y = 30; 
pt2.x = 10; 
pt2.y = 40; 

gm_$rectangle_16( ptl, 
pt2, 
false, 
St); 

gm_$dra¥_style( gm_$solid, 
(short) 0, 
pattern, 
(short) 0, 
St) ; 

ptl .X = 20; 

pt2.x = 30; 

gm_$rectangle_16( ptl, 
pt2, 
false, 
St) ; 

gm_$segment_close( true, 
St) ; 

gm_$segment_create("top" , 

(short) 3, 

sid2, 

St); 

ptl .X = 0; 
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ptl .y = 0; 
pt2.x = 10; 
pt2.y = 10; 

gm_$rectangle_16( ptl, 
pt2. 
false. 
St); 

gm_$lnstance_translate_2dl6 ( sidl . 

ptl. 

St); 
ptl .X = 20; 
pt2.x = 30; 

gm_$rectangle_16( ptl. 
pt2. 
false. 
St); 

gm_$segment_close( true. 
St); 

gm_$display_f ile(st) ; 

/* Display segments In the other two viewports . */ 

gm_$viewport_select( vpid2. 

St); 

gm_$display_file(st) ; 

gm_$viewport_select( vpidl. 

St); 
gm_$display_f ile (st) ; 

pause. low32 = 5 * one_second; 

pause .liighie = 0; 

time_$¥ait (time_$relative „ pause . st) ; 

/* Assign different attributes to each viewport. */ 

gm_$ablock_create ( (short) 1 . 
abloclcidl. 
st); 

gm_$ablock_set_draw_style ( ablockidl . 

gm_$dotted. 
(short) 5. 
pattern, 
(short) 0, 
st); 

gm_$ablock_assign_viewport ( aclassidl . 

vpidl. 
ablockidl. 
st) ; 

gin_$ablock_create ( (short) 1 . 
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ablockid2, 
St); 

gm_$abloclc_set_dra¥_style ( ablock:id.2, 

gm_$<iotted, 
(short) 10. 
pattern, 
(short) 0. 
St): 

gm_$ablock_assign_vie¥port( aclassidl. 

vpid2, 
ablockld2. 
St); 

gm_$ablock_create ( (short) 1 . 
ablockidS. 
St) ; 

gm_$ablock_set_draw_style ( ablockidS. 

gm_$dotted. 
(short) 20. 
pattern. 
0. 
St) ; 

gm_$ablock_assign_viewport ( aclassldl . 

vpidS. 
ablockidS. 
St); 

gni_$display_refresh(st) ; 

time_$wait( time_$relative. 
pause. 
St); 

/* Add an attribute class command. */ 

gm_$segment_create("new" . 

(short) 3. 
sid3. 
St) ; 

ptl .X = 0; 
ptl .y = 0; 
pt2.x = 10; 
pt2.y = 10; 

gm_$rectangle_16( ptl. 
pt2. 
false. 
St) ; 

gm_$aclass( aclassld2. 

St); 
ptl.x = 20; 
pt2.x = 30; 
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gm_$rectangle_16( ptl, 
pt2. 
false. 
St); 

gin_$segment_close( true. 
St) : 

/* Assign attribute blocks to the attribute class. */ 

gm__$ablock_create ( (short) 1 , 
ablockid4. 
St) ; 

gm_$ablock_set_draw_style ( ablockid4 . 

gm_$dotted, 
(short) 30. 
pattern, 
(short) 0. 
st) ; 

gm_$ablock_assign_vie¥port( aclassid2. 

vpidl. 
ablockid4. 
St) ; 

gm_$ablock_create( (short) 1. 
ablockidS. 
St) ; 

gm_$ablock_set_dra¥_style ( ablockidS . 

gm_$dotted. 
(short)40. 
pattern, 
(short) 0. 
st); 

gm_$ablock_assign_vie¥port( aclassid2. 

vpid2. 
ablockidS. 
st) ; 

gm__$ablock_create ( (short) 1 . 
ablockldS. 
st) ; 

gm_$ablock_set_draw_style ( ablockidS . 

gm_$dotted. 
(short) 50, 
pattern, 
(short) 0. 
st) ; 

gm_$ablock_assign_vlewport( aclassid2. 

vpid3. 
ablockide. 
st) ; 

gm_$display_segment( sidS. 



G Program Examples E-34 



St); 

gin_$viewport_select( vpid2, 

St); 

gm_$dlsplay_segmeiit( sid3. 

St); 

gm_$vlewport_select( vpidS. 

St); 

gm_$display_segment( sld3, 

St); 

tlme_$walt( tlme_$relative. 
pause, 
St); 

gm_$f ile_close( true, 
St); 

gm_$terminate(st) ; 
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Program with Advanced Viewing Techniques 

The following program changes the color map values; assigns a plane mask to viewports; displays 
a grid; changes the plane mask; assigns viewport background values; displays segments in more 
than one viewport; closes the file; and terminates the package (see Section 14.3). 



/* PROGRAM courses */ 

#nolist 

#include <stdio.h> 

#include "/sys/ins/base.ins.c" 

#include "/sys/ins/time. ins .c" 

#include " /sys/ins/gmr . ins . c " 

#include "/sys/ins/pfm. ins .c" 

#list 



#define gm_default_aclass 1 

#define repeats 10 

#define space 25 

#deflne one_second 250000 

#deflne planeO 1 
#define planei 2 
#deflne plane2 4 



gm_$pointl6_t bitmap_sizej 

status_$t st; 

gm_$l)oundsreal_t b; 

short vpid2, vpidS. vpid4: 

short ablockid; 

short k; 

short m ,n; 

gin_$color_entry_t color_array [8] ; 

short file_id; 

gm_$segment_id_t sldl, sid2, sid3 , sid4; 

gm_$pointl6_t ptl, pt2, transl; 

gm_$pointreal_t rtransl; 

gin_$plane_mask_t mask; 

check(status) 

status_$t status; 

if (status .all != status_$ok) 
pfm_$error_trap (status) ; 
> 

waltO 

{ 

time_$clock_t pause; 

status_$t status; 

pause . low32 = 5 * one_second; 
pause. highie = 0; 
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/* Wait five seconds. */ 

time_$wait( time_$relative, 
pause, 
status) ; 
check(status) j 
> 

mainC) 
< 

bitmap_size .X = 1024; 
bitmap_slze .y = 1024; 

/* Initialize the 2D GMR package . */ 

gm_$init( gin_$borrow, 

stream_$stdout, 
bitmap_size, 
(short) 8, 
St); 

/* Create and name a metafile. */ 

gm_$f ile_createC "gmfile", 
(short) 6, 
gm_$overwrite. 
gm_$l¥. 
file_id. 
St) ; 

/* Create segment 'grid. ' */ 

gm_$segment_create ( "grid" , 

(short) 4, 
sidl, 
St) ; 

/* 'Grid* points are zero-sized rectangles. */ 



ptl 


.X = 


0; 










for(m=l: 


; m<: 


=8; 1 


n++) 






i 
















ptl 


x = 


ptl 


.X + 


100; 






ptl 


■ y = 


0; 










for(n=l 


; n<: 


=8; ] 


a++) 






< 
















ptl 


• y = 


ptl 


■ y + 


100; 






gm_; 


$rectang: 


Ie_16( ptl. 














ptl. 














false. 














St); 



>/* end for n */ 
>/* end for m */ 

/* Close segment 'grid.* */ 

gm_$segment_close( true, 
st); 
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b.xmin = 0.0; 
b.ymin =0.0; 
b.xmax = 0.49; 
b.ymax = 0.49; 

/* Shrink viewport 1 . */ 

gm_$viewport_set_bounds( b, 

St) 

b.xmin = 0.51; 
b.ymin =0.0; 
b . xmax = 1.0; 
b . ymax = 0.49; 

/* Create viewport 2. */ 

gm_$viewport_create( b, 

vpi(i2. 

St) : 

b.xmin =0.0; 
b.ymin = 0.51; 
b.xmax = 0.49; 
b . ymax = 1.0; 

/* Create viewport 3. */ 

gm_$viewport_create( b, 

vpidS, 
St); 

b.xmin = 0.51; 
b.ymin = 0.51; 
b . xmax = 1.0; 
b . ymax = 1.0; 

/* Create viewport 4. */ 

gm_$viewport_create( b. 

vpi<i4, 
St) ; 



/* Red + green = yellow. */ 
for(k=0; k<8; k++) 
< 

color_array[k] .red = 1.0; 

color_array[k] .green = 1.0; 

color_array [k] .blue = 0.0; 
> 

/* Set color values 8 to 15 to yellow. */ 

gm_$display_set_color_map( OL, 

0, 

color_array, 
st) ; 
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/* Create an ablock. */ 

gm_$ablock_create( (short) 1, 
abloclcid, 
St) ; 

/* For the ablock, set the draw value to 9 . */ 

gm_$ablock_set_draw_value ( ablockid, 

(short) 9, 
St) ; 

/* Assign the ablock to the default aclass . */ 

gm_$ablock_asslgn_display( gm_def ault_aclass, 

ablockid. 
St) : 

/* Display 'grid' in viewport 4. */ 

gm_$display_f ile(st) ; 
/* Wait a moment . */ 

waitO ; 

/* Reset the ablock to default attributes . */ 

gm_$ablock_copy ( (short) 1 , 
ablockid, 
St) : 

/* For the ablock, set plane mask to [0.1,2]. */ 

mask = ( planeO | planel I plane2 ) ; 

gm_$ablock_set_plane_mask( ablockid, 

true, 
mask, 
St); 

/* Create segment 'box.' */ 

gm_$segment_create ( "box" , 

(short) 3, 
sid2, 
St) ; 

ptl .X = Oj 
ptl.y = 0; 
pt2.x = 10; 
pt2.y = 10; 

/* Add a rectangle to 'box. ' */ 

gm_$rectangle_16( ptl, 
pt2, 
false, 
St) ; 
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/* Close segment 'box.' */ 

gm_$segment_close( true, 
St) ; 

/* Create segment 'row. ' */ 

gm_$segment_create ( "row" . 

(short) 3. 
sid3, 
St) ; 

/* Instance segment 'box' into segment 'row. ' */ 
transl .y = 0; 
transl .x = 0; 
for(k=0; k<repeats; k++) 
< 

transl. X = transl. x + space; 
gm_$instance_translate_2dl6( sid2, 

transl, 
St) : 
> 

/* Close segment 'row. ' */ 

gm_$segment_close ( true , 

St) j 

/* Create segment 'block.' */ 

gm_$segment_create( "block", 

5, 

sid4, 
St) ; 

/* Instance segment 'row' into segment 'block. ' */ 

transl .y = 50; 

for(k=0; k<repeats; k++) 

i 

transl. X = k ; 

transl. y = transl. y - space; 

gm_$instance_translate_2dl6( sidS, 

transl, 
St); 
> 

/* Close segment 'block.' */ 

gm_$segment_close ( true, st) ; 

/* Display segment 'block' in viewport 3. */ 

gm_$display_segment( sid4, 

St); 

/* Wait a moment. */ 
waitO ; 
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rtransl.x =0.5; 
rtransl.y = 1.0; 

/* For viewport 3, zoom out. */ 

gm__$view_scale( (float) 0.25, 
rtransl. 
St); 

rtransl.x = -0.06; 
rtransl.y =0.0; 

/* For viewport 3. pan from left to right. */ 
for(k=0; k<5; k++) 

gm_$view_translate( rtransl, 
St); 

rtransl.x =0.5; 
rtransl.y = 0.5; 

/* For viewport 3, pan diagonally towards lower left. */ 
for(k=0; k<5; k++) 

gm_$view_scale ( (float) 0.85, 
rtrailsl, 
St); 

/* Wait a moment. */ 
waitO ; 

/* For viewport 2, set the background value to 2. */ 

gm_$viewport_set_background_value ( vpid2, 

2L, 
St); 

/* Select viewport 2. */ 

gm_$viewport_select( vpid2, 

St); 

/* Display segment 'row' in viewport 2. */ 

gm_$display_segment( sid3, 

St); 

/* Wait a moment. */ 
waitO ; 

/* For viewport 3, set background value to 2. */ 

gm_$viewpor t_set_background_value ( vpidS , 

3L, 



St); 



/* Select viewport 3. */ 

gm_$viewport_select( vpidS. 

St) ; 
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/* Display segment 'block' in viewport 3. */ 

gm_$(iisplay_segment( sid4, 

St) ; 

/* Walt a moment . */ 
waitO : 

/* Close the file. */ 

gm_$file_close( true, 
St); 



/* Terminate the 2D GMR package . */ 

gm_$terminate(st) ; 
} 
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Attributes and Instancing 

The following program displays a file as it is being created and edited. The file creates the 
picture in Figure D-1. 

/* PROGRAM hotel. pas */ 



#nolist 

#lnclude <stdio.h> 

#include "/sys/lns/base .Ins.c" 

#include "/sys/ins/error . ins .c" 

#include "/sys/ins/pfm. ins.c" 

#include "/sys/ins/gmr .ins.c" 

#include "/sys/ins/time . ins.c" 

#list 



#define one_second 250000 

#define five_seconds (5 * one_second) 

status_$t status; 

short file_id; 

short font_f ile_id; 

gin_$segment_id_t sid_scene: 

gm_$segment_id_t sid_door; 

gm_$segment_id_t sid_windo¥; 

gm_$segment_id_t sid_sign; 

gm_$segment_id_t sid_tree; 

gm_$segment_id_t sid_house; 

gm_$draw_pattern_t pattern: 
gm_$point_arrayl6_t p; 

gm_$pointl6_t center; 

short radius; 

short i; 

time_$clock_t pause; 

check (status) 

status_$t status; 
i 

if (status .all != status_$ok) 
pfm_$error_trap (status) ; 
> 

mainO 

< 

/* Intialize GMR package. */ 

pCO] .X = 1024; 

pCO] .y = 1024; 

gm_$init( gm_$direct, 

streain_$stdout, 
p[03. 
(short) 8, 
status) ; 

check(status) ; 
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/* Create and name a metafile . */ 

gm_$file_create( " hotel. gm", 
(short) 8, 

gm_$overwrite, 

gm_$l¥, 

file_id. 

status) ; 
check (status) ; 

/* Load a font family. */ 

gm_$f ont_f amily_include ( "f f 0" , 

(short) 3, 
gm_$pixel, 
font_file_id, 
status) ; 

check (status) ; 

/* Set the data coerce . */ 

gm_$data_coerce_set_real ( gm_$32, 

status) ; 
check(status) ; 



/* Create the segment for the door . */ 

gm_$segment_create ( (char *)NULL, 

(short) 0. 
sid_door, 
status) ; 

check (status) ; 

/* Construct the door. */ 
pCO] .X = 0; 
p[0].y = 0; 
p[l] .X = 36; 
p[l] .y = 80; 

gm_$rectangle_16 ( p [0] , 

p[l]. 
true, 
status) ; 
check (status) ; 

/* Construct the door knob. */ 

gm_$fill_value( OL, 

status) ; 
check (status) ; 

p[0] .X = 30; 
p[0].y = 38; 
p[l] .X = 33; 
pCl].y = 41; 

gm_$rectangle_16( p[0]. 
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true, 
status) : 
check (status) ; 

gm_$segmeiit_close ( true, 

status) ; 
clieck (status) ; 

/* Create the segment for the windows . */ 
gm_$segment_create ( (char *)NULL, 

(short) 0, 
sid_window, 
status) ; 
check (status) ; 

p[0] .X = 0; 

pCO] .y = 0; 

p[l] .X = 36; 

pCl] .y = 36; 

gin_$rectangle_16( p[0], 
pCl], 
false, 
status) ; 

check(status) ; 

pCo] .X = 0; 

pCo] .y = 18; 

pCl] .X = 36; 

p[l] .y = 18; 

gm_$polyline_2dl6( (short) 2, 

false, 
false, 
status) ; 
check (status) ; 

p[0] .X = 18; 

pCo] .y = 0; 

pCl] .X = 18; 

p[l] .y = 36; 

gm_$polyline_2dl6( (short) 2, 

P- 

false, 

false, 
status) ; 
check(status) ; 

gm_$segment_close ( true , 

status) ; 
check (status) ; 



/* Create the segment for the sign. */ 
gm_$segment_create( (char *)NULL, 

(short) 0, 
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sid_sigii, 
status) ; 



check(status) ; 



gm_$text_slze( (float) 14.0, 
status) ; 

check(status) ; 

p[0] .X = 0; 
p[0] .y = Oj 

gm_$text_2dl6( p [0] , 

(float)O.O, 
"GRAND MOTEL", 
(short) 11, 
status) ; 

check (status) ; 

gm_$segment_close ( true, 

status) ; 

check(status) ; 



/* Create the segment for the house . */ 
gm_$segment_create( (char *)NULL, 

(short) 0, 
sici_house, 
status) ; 

check(status) ; 

/* Build the house. */ 
p[0] .X = 0; 
p[0] .y = 0; 
p[l] .X = 480; 
p[l] .y = 260; 

gm_$rectangle_16( p[03, 

p[l], 
false, 
status) ; 

check (status) ; 

/* Build the roof . */ 
p[0] .X = -10, 



p[0] 
p[l] 
p[l] 
p[2] 
p[2] 



y = 255 
X = 240; 
y = 380 
X = 490 
y = 255; 



gm_$polyline_2dl6( (short) 3, 

P- 
false. 
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false, 
status) 



check (status) ; 



/* Build the chimney. */ 



p[0] 


X = 300; 


p[0] 


y = 350; 


p[l] 


X = 300; 


p[l] 


y = 370; 


p[2] 


X = 330; 


pC2] 


y = 370; 


pC33 


X = 330; 


p[3] 


y = 335; 


gm_$polyline_2dl6( (short) 4 


P' 


false. 


false. 




status) 



check (status) ; 



/* Build the round window, 
center. X = 240; 
center. y = 195; 
radius = 45; 



*/ 



gm_$circle_16( center, 
radius, 
false, 
status) ; 

check(status) ; 



PCO] 
p[0] 
pCl] 
pCl] 
pC2] 
p[2] 
p[33 
p[3] 



X = center. X - radius. 

y = center. y; 

X = center. X + radius. 

y = center. y; 

X = center. x; 

y = center. y - radius, 

X = center. x; 

y = center. y + radius. 



gm_$polyline_2dl6( (short)4, 

P- 

true, 
false, 
status) ; 

check(status) ; 

p[4] .X = p[l] .x; 
p[4] .y = p[l] .y; 
p[l] .X = p[2] x; 
p[i] .y = p[2] -y; 

gin_$polyline_2dl6( (short) 2. 
P' 
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false, 
false, 
status) ; 



check (status) ; 



gm_$polyline_2dl6( (short) 2, 

p[3], 
false, 
false, 
status) j 

check (status) ; 

/* Instance and position the door. */ 
pCO] .X = 222; 
p[0] .y = 0; 

gm_$instance_translate_2dl6( sid_door, 

p[0], 
status) ; 

check (status) ; 

/* Instance and position the windows . */ 
p[0] .X = 50; 
p[0] .y = 40; 

gin_$instance_translate_2dl6 ( sid_window, 

pCO], 
status) ; 

check(status) ; 

p[0] .X = 118; 

gm_$instance_translate_2dl6 ( sid_¥indow. 

pCO], 
status) ; 

check (status) ; 

p[0] .X = 326; 

gm_$instance_translate_2dl6 ( sid_¥indow, 

p[0], 
status) ; 

check (status) ; 

p[0] .X = 394; 

gm_$instance_translate_2d:L6 ( sid_window, 

p[o], 
status) ; 

check (status) ; 

p[0] .y = 180; 

gm_$instance_translate_2dl6 ( sid_window, 

p[0]. 
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status) : 
check(status) ; 
p[0] .X = 326; 

gni_$instance_translate_2dl6 ( si<i_¥indow, 

p[0], 
status) ; 

check (status) ; 

p[0] .X = 118; 

gm_$lnstance_translate_2(il6 ( sid_wlndow, 

p[0], 
status) ; 

check(status) ; 

p[0] .X = 50; 

gm_$instance_translate_2dl6 ( sid_window, 

pCO], 
status) ; 

check(status) ; 



/* Instance and position the segment for the sign. */ 
p[0] .X = 172; 
p[0] .y = 120; 

gm_$instance_translate_2dl6( sid_slgn. 

p[0], 
status) ; 

check(status) ; 

gm_$segment_close ( true, 

status) ; 

check (status) ; 



/* Create the segment for the trees. */ 
gm_$segment_create( (char *)NULL, 

(short) 0, 
sid_tree, 
status) ; 

check(status) ; 

p[0] .X = 0; 
p[03 .y = 0; 
pCl] .X = 0; 
p[l] .y = 150; 
gm_$polyline_2dl6( (short) 2. 

P' 
false. 
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false, 
status) ; 

check(status) ; 

p[0] .X = 12; 
p[l3 .X = 12; 

gm_$polyline_2dl6( (short) 2, 

false, 
false, 
status) . 

check(status) ; 

p[0] .X = 6; 

p[0] .y = 200; 

gm_$circle_16( p[03, 

(short) 50, 
false, 
status) ; 

check (status) ; 

gm_$dra¥_style( gm_$dotted, 
(short)2, 
pattern, 
(short) 0, 
status) ; 

pCO] .X = 0; 
p[0] .y = 180; 
p[l] .X = -40; 
p[l] .y = 200; 

gm_$polyline_2dl6( (short) 2, 
p. 

false, 
false, 
status) ; 

check (status) ; 

pCO] .X = 12; 
p[l3 .X = 52; 

gm_$polyline_2dl6( (short) 2, 

P' 

false, 
false, 
status) , 

check(status) ; 

pCO] .X = 4; 
p[0] .y = 190; 
p[l] .X = -20; 
p[l] .y = 230; 
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gm_$polyline_2<il6( (short) 2, 

false, 
false, 
status) ; 

check(status) ; 

p[0] .X = 8; 
p[0] .y = 190; 
p[l3 .X = 32; 
p[l] .y = 230; 

gm_$polyline_2dl6( (short) 2. 

P- 

false, 
false, 
status) ; 

check: (status) ; 

p[0] .X = 6; 

p[0] .y = 195; 

p[l] .X = 6; 

p[l] .y = 240; 

gm_$polyline_2dl6( (short)2, 

P- 

false, 
false, 
status) ; 
check(status) ; 

pCO] .X = 0; 

p[0] .y = 170; 

p[l] .X = 0; 

p[l3 .y = 150; 

gin_$polyline_2dl6( (short) 2, 

P. 
false, 

false, 

status) ; 

check(status) ; 

p[0] .X = 12; 
pCl] .X = 12; 

gm_$polyline_2dl6( (short) 2, 

P' 
false, 

false, 

status) ; 

check (status) ; 

gin_$segment_close( true, 

status) ; 
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check(status) ; 



/* Create the segment called scene . */ 

gin_$segment_create( (char *)NULL. 

(short) 0. 
si{i_scene, 
status) ; 

check (status) ; 

p[03.x = 0; /* Instance the segment HOUSE. */ 

p[0] .y = 0; 

gm_$instance_translate_2(il6( si(i_house, 

p[0], 
status) ; 

check (status) : 

/* Instance, translate, and scale the segment the trees. */ 
pCO] .X = -85; 
pCO] .y = -25; 

gm_$instance_scale_2dl6 ( sid_tree , 

(float) 2.0. 
p[0]. 
status) ; 

p[0] .X = 530; 
p[0].y = 55; 

gm_$instance_scale_2dl6 ( sid_tree . 

(float)0.75. 
p[0], 
status) ; 

check (status) ; 

p[0] .X = 610; 
p[0] .y = 105; 

gm_$instance_scale_2dl6( sid_tree. 

(float) 0.85, 
p[0], 
status) ; 

check (status) ; 

gm_$segment_close( true, 

status) ; 

check (status) ; 



/* Now display the completed scene . */ 
gm_$display_segment( sid_scene, 
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status) ; 

check(status) ; 

/* Admire the scene for five seconds. */ 
pause . low32 = f ive_seconds j 
pause .liigliie = 0; 

time_$wait( time_$relative, 
pause, 
status) ; 

check (status) ; 

/* Close and save the file . */ 

gm_$f ile_close( true. 

status) ; 

check (status) j 

/* Terminate the 2D GMR package . */ 
gm_$terminate (status) ; 

check (status) ; 
> 
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Appendix F 
FORTRAN Program Examples 



This Appendix contains some of the programming examples presented in the manual translated 
into FORTRAN. 

A Program to Draw a Rectrangle 

The following program demonstrates how to initialize the 2D GMR package, create a metafile, 
create a segment, and draw a rectangle (see Section 3.8 and Figure 3-3). 



program draw_rectangle 
%lnclude */sys/lns/base . ins .f tn' 
%include '/sys/ins/gmr . ins .ftn' 
%include '/sys/ins/time . ins .f tn' 



integer*2 


file_id 


lnteger*4 


segment id 


integer*4 


St 


integer*2 


ptl(2) ,pt2(2) 


lnteger*4 


i 


integer*2 


bitmap size (2) 


integer*2 


pause (3) 


integer*2 


liigh_plane 




{ Define the coordi 


ptl(l) = 100 




ptl(2) = 30 




pt2(l) = 200 




pt2C2) = 50 





bitmap_size(l) = 1024 
bitmap_slze(2) = 1024 



call gm_$init( 
+ gm_$direct 
+ ,stream_$stdout 
+ .bitmap_size 

+ ,high_plane 
+ , st 
) 



call gm_$f ile_create( 
'gmfile' 
,int2(6) 
,gm_$overwrite 
,gm_$lw 
,file_id 
, st 
) 



{ Initialize 2D GMR. > 



•C Create and name metafile. > 



< Create and name a segment . > 
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call gm_$segmeiit_create 
+ ('rectang_seg' 

+ .int2(ll) 

+ , segment_id 

+ ,st 

+ ) 



call gm_$rectangle_16 
+ (ptl 

+ ,pt2 

+ , false 

+ ,st 

+ ) 



{ Insert a rectangle . > 



call gni_$display_file 
( 

+ St 
) 



{ Display the file. > 



pause (1) = 

pause (2) = 20 

pause (3) = 

call time_$¥ait( 
+ time_$relative 
+ .pause 
+ ,st 
+ ) 



"C Display the figure for five seconds. > 



call gm_$segment_close( 
+ true 
+ ,st 
■^ ) 



{ Close the segment. > 



i Close the metafile. } 



call gm_$file_close( 
+ true 
+ .st 
-^ ) 

call gm_$termlnate ( 
+ st 
+ ) 

END 
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A Program Using Primitives and Instancing 

The following program draws the design in Figure 4-2 using primitives and instancing (see 
Section 4.6). 



program draw_rectangle 

%nolist 

%include " /sys/lns/base . ins . f tn ' 

%lnclude '/sys/ins/gmr .ins .ftn' 

%include '/sys/ins/time .ins.ftn' 

%llst 



integer*2 
integer*4 
integer*4 
integer*4 
integer*2 
integer*4 
lnteger*2 
integer*2 
integer*2 
character 
integer*2 



file_id 

small_ld 

large_ld 

St 

ptl(2). pt2(2) 
i 

bltmap_size(2) 
position(2) 
positions (4) 
pattern (8) 
pause (3) 



bitmap_size(l) = 1024 
bitmap_size(2) = 1024 



call gm 


_$init 


+ 


(gm_$direct 


+ 


, stream $stdout 


+ 


,bitmap_size 


+ 


,int2(8) 


+ 


.st 


+ 


) 


call error (st) 


call gm 


$f ile_create 


+ 


Cgmfile' 


+ 


.int2(6) 


+ 


, gm_$over write 


+ 


.gm_$lw 


+ 


,file_id 


+ 


,st 


+ 


) 


call error (st) 


ptl(l) 


= 100 


ptl(2) 


= 100 


pt2(l) 


= 200 


pt2(2) 


= 200 



■C Initialize 2D GMR. > 



< Create and name a metafile . > 



i Define coordinates of a rectangle . > 
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call gm_$segment_create 
+ (•small_rec* 
+ ,int2(9) 
+ .small_id 
+ ,st 
) 

call error (st) 



{ Create and name a segment. > 



call gm_$rectangle_16 
+ (ptl 
+ .pt2 
+ , . true . 
+ ,st 
) 

call error (st) 



< Draw a rectangle . > 



call gm_$segment_close 
+ ( . true . 
+ .st 
+ ) 

call error (st) 



< Close the segment. > 



call gm_$segment_create 
+ ( • large_rec ' 
+ .int2(9) 
+ . large_id 
+ ,st 
+ ) 

call error (st) 

call gm_$draw_style 
+ (gm_$solid 
+ ,int2(4) 
+ .pattern 
+ .int2(0) 
+ ^ st 
) 

call error (st) 



ptl(l) = 100 

ptl (2) = 100 

pt2(l) = 600 

pt2(2) = 600 



{ Define the coordinates of the rectangle to be drawn. > 



call gm_$rectangle_16 
+ (ptl 
+ ,pt2 
+ , .false. 
+ .st 
) 

call error (st) 



■C Draw an unfilled rectangle. > 
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positlon(l) = 100 
posltion(2) = 100 



call gin_$instaiice_translate_2dl6 
+ (small_id 

+ .position 

+ ,st 

+ ) 

call error (st) 



< Instance the rectange four times . > 



positiond) = 300 
position(2) = 300 

call gm_$instance_translate_2dl6 
+ (small_id 
+ , position 
+ .St 
+ ) 

call error (st) 

position(l) = 300 
position(2) = 100 

call gin_$instance_translate_2dl6 
+ (small_id 
+ .position 
+ .st 
) 

call error (st) 

positlon(l) = 100 
position(2) = 300 

call gm_$instance_translate_2dl6 
+ (small_id 
+ .position 
+ .st 
) 

call error (st) 



positions (1) = 300 
positions (2) = 300 
positions (3) = 400 
positions (4) = 400 



call gm_$polyline_2dl6 
+ (int2(2) 
+ .positions 
+ . .false. 
+ . .false . 
+ .st 
+ ) 

call error (st) 



•C Draw a line connecting the rectangles. > 



positions (1) = 300 
positions (2) = 400 
positions (3) = 400 
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positions (4) = 300 



call gm_$polyline_2dl6 
+ (int2(2) 
+ .positions 
+ , ; false . 
+ . .false . 
+ ,st 
+ ) 

call error (st) 



call gin_$segment_close 
+ ( . true . 

+ ,st 

+ ) 

call error (st) 

call gm_$display_segment 
+ (large_id 
+ .st 
+ ) 

call error (st) 



-C Close the segment. > 



pause (1) = 

pause (2) = 20 

pause (3) = 

call time_$wait 
+ ( time_$relative 
+ . pause 
+ . st 
+ ) 

call error (st) 



< Display the figure for five seconds . > 



< Close the metafile. > 



call gm_$file_close 
+ ( . true . 
+ .st 
+ ) 

call error (st) 

call gm_$terminate 
+ ( 
+ st 
) 

call error (st) 

END 

subroutine error (st) 

integer*4 st 
%include ' /sys/ins/base . ins . f tn ' 
^include '/sys/ins/pfm. ins .f tn' 

if (st .ne. 0) then 
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call pfm_$error_trap(st) 
endif 
return 
end 
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A Program Including Text 

The following program draws the design in Figure 6-1. This is a rectangle with horizontal and 
vertical text strings (see Section 6.5). 

program draw_rectangle_text 

%incliide '/sys/ins/base. ins . ftn' 

%include '/sys/ins/gmr . ins .f tn' 

%include '/sys/ins/time . ins .fta' 

^include '/sys/ins/error . ins . ftn ' 



integer*2 




file_id 


lnteger*4 




segment id 


integer*4 




st 


integer*2 




ptl(2), pt2(2),point(2) 


integer*4 




i 


integer*2 




bitmap_size(2) 


integer*2 




ffid 


integer*2 




pause (3) 


bitmap_size 


(1) 


= 1024 


bitmap_size 


(2) 


= 1024 



call gm_$init 



(gm_$direct 

, stream_$stdout 

,bitmap_size 

,int2(8) 

,st 

) 



call error (st) 



call gm_$f ile_create 



4- 


('gmf ile' 


+ 


,int2(6) 


+ 


,gm_$overwrite 


+ 


,gm_$lw 


+ 


,file_id 


+ 


.st 



) 

call error (st) 



< Initialize 2D GMR. > 



-C Create and name a metafile . > 



call gm_$segment_create 
('rectang_seg' , 

'r int2(ll) 

,segment_id 
.st 

- ) 

call error (st) 



{ Create and name a segment. > 



call gm_$font_family_include 
+ ( "font families' 



{ Load the font family. > 
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■4- 


. illt2(13) 


+ 


. gm_$pixel 


+ 


. ffid 


+ 


, St 


+ 


) 


call 


error (st) 


call 


gni_$text_size 


+ 


(14.0 


+ 


- St 


+ 


) 


call 


error (st) 



point(l) = 5 
point (2) = 510 

"C Display a line of text. > 
call gm_$text_2dl6 
+ ( point, 0.0 

+ , 'This is the top of the rectangle." 
+ , int2(33) 
+ . st 
) 
call error (st) 

point(l) = 5 
point (2) = 50 

< Display a line of text. > 

call gni_$text_2cil6 
+ ( point 
+ , -90.0 

+ , 'This is the side of the rectangle.' 
+ . int2(34) 
+ . st 
+ ) 

call error (st) 

< Define the coordinates of the rectangle to be drawn. } 
ptl(l) = 10 
ptl(2) = 30 
pt2(l) = 400 
pt2(2) = 500 

< Draw a rectangle . > 

call gin_$rectangle_16 
+ (ptl 

+ ,pt2 

+ , false 

+ .st 

+ ) 

call error (st) 

■C Close the segment. > 

call gm_$segment_close 
+ ( . true . 
+ ,st 
+ ) 

call error (st) 
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{Display the filG.> 
call gm_$display_file 

+ (st 

+ ) 
call error (st) 



pause (1) = 

pause (2) = 20 

pause (3) = 

call time_$wait 
+ ( tlme_$relative 
+ , pause 
+ , st 
) 

call error (st) 



call gm_$file_close 
+ ( true 
+ ,st 
) 

call error (st) 



call gm_$terminate 
+ ( st 
+ ) 

call error (st) 

END 

subroutine error (st) 

integer*4 st 
%include '/sys/ins/base . ins .f tn' 
%include '/sys/ins/pfm. ins .ftn* 

if (st .ne. 0) then 

call pfm_$error_trap(st) 

endif 

return 

end 



{ Display the figure for five seconds . > 



{ Close the metafile. } 



■C Terminate 2D GMR. > 
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A F^ogram with Attribute Classes and Blocks 

The following program creates a hierarchy of segments including instance commands. It displays 
the file in three viewports; adds attribute class commands to the file; assigns attribute blocks to 
attribute classes; displays the segments; closes the file; and terminates the package (see Chapter 

13). 



PROGRAM courses 

(INCLUDE • /sys/ins/base . ins . f tn ' 
^INCLUDE '/sys/ins/time.ins.ftn' 
jINCLUDE Vsys/ins/gmr .ins.ftn' 



integer*2 


aclassidl 


integer*2 


aclassid2 


integer*2 


vpidl 


integer*2 


vpid2 


integer*2 


vpid3 


integer*2 


bitmap size (2) 


integer*4 


status 


real 


b(4) 


integer*2 


file_id 


integer*4 


sidl 


integer*4 


sid2 


integer*4 


sid3 


integer*2 


ablockidl 


integer*2 


ablockid2 


integer*2 


ablockidS 


lnteger*2 


ablockid4 


integer*2 


ablockidS 


integer*2 


ablockide 


integer*2 


ptl(2) 


integer*2 


pt2(2) 


character 


pattern (8) 


integer*2 


pause (3) 


aclassidl = 


1 < Default 


aclassld2 = 


2 


vpidl = 


1 < Initial 



bitmap_size(l) = 1024 
bitmap_size(2) = 1024 



call gm_$init 
+ ( gm_$borrow 
+ , stream_$stdout 
+ , bitmap_size 
+ , int2(8) 
+ . status 
■*- ) 

b(l) = 0.00 

b(2) =0.00 



■C Initialize the 2D GMR package . > 



F-11 



FORTRAN Program Examples 



b(3) = 0.49 
b(4) = 0.49 



call gm__$vie¥port_set_botinds 
+ ( b 

+ , status 



) 



{ Create viewport 1 . > 



b(l) 


= 0.51 


b(2) 


= 0.00 


b(3) 


= 1.00 


b(4) 


= 0.49 


call 


gm $¥iewport create 


+ 


( b 


+ 


. ¥pi(i2 


+ 


, status 


+ 


) 


b(l) 


= 0.00 


b(2) 


= 0.51 


b(3) 


= 1.00 


b(4) 


= 1.00 



-C Create viewport 2. } 



{ Create viewport 3. > 



call gm__$vie¥port_create 
+ ( b 
+ . vpid3 
+ . status 
) 



call gm_$f ile_create 
( 'gmflle' 
. int2(6) 

, gm_$overwrite 
, gm__$l¥ 
, file__id 
, status 



) 



call gm 


_$segment create 


(" 


'bottom' 


+ 


lnt2(6) 


+ 


sidl 


+ 


status 


+ ) 




ptl(l) : 


= 


ptl(2) : 


= 30 


pt2(l) : 


= 10 


pt2(2) : 


= 40 



{ Create a file. } 



{ Create 'bottom' segment. } 



call gm_$rectangle_16 



{ Add a rectangle to 'bottom' segment. > 
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+ ( ptl 

+ . pt2 

+ . .FALSE. 

+ . Status 

+ ) 



call gm_$draw_style 

+ ( gm_$solid 

+ , iiit2(0) 

+ . pattern 

+ . int2(0) 

+ , status 

^ ) 



{ Change the draw style to solid. > 



ptl(l) = 20 
pt2(l) = 30 



call gm_$rectangle_16 
+ ( ptl 
+ . pt2 
+ . .FALSE. 
+ . status 
+ ) 



< Add a rectangle to 'bottom' segment. } 



call gm_$segment_close 
+ ( .TRUE. 
+ , status 
) 



< Close 'bottom' segment. } 



call gm_$segment_create 
+ ( ' top ' 
+ . int2(3) 
+ . sid2 
+ . status 
+ ) 



-C Create 'top' segment. > 



ptl(l) = 
ptl (2) = 
pt2(l) = 10 
pt2(2) = 10 



call gm_$rectangle_16 
+ ( ptl 
+ , pt2 
+ , .FALSE. 
+ , status 
) 



< Add a rectangle to 'top' segment. > 



< Instance 'bottom' into 'top' segment. > 
call gm_$instance_translate_2dl6 
+ ( sidl 
+ , ptl 
+ , status 
) 
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ptl(l) = 20 
pt2(l) = 30 



call gm_$rectangle_16 
+ ( ptl 
+ , pt2 
+ . .FALSE. 
+ , status 
-»■ ) 



call gm_$SGgment_close 
+ ( .TRUE. 
+ . status 
+ ) 



call gm_$display_file 
( status 



) 



call gm_$viewport_select 
+ ( vplci2 
+ , status 
) 



< Add a rectangle to 'top' segment. > 



■C Close 'top* segment. } 



{ Display the file in viewport 3. > 



-C Select viewport 2. > 



call gm_$display_file 
( status 
) 



■C Display the file in viewport 2. } 



call gm_$viewport_select 
+ ( vpidl 
+ , status 
+ ) 



{ Select viewport 1 . } 



call gm_$display_f ile 
+ ( status 
+ ) 

pause (1) = 

pause (2) = 20 

pause (3) = 

call time_$walt 
+ ( time_$relative 
+ . pause 
+ , status 
) 



-C Display file in viewport 1. > 



call gm_$ablock_create 
+ ( int2(l) 
+ , ablockidl 
+ . status 
+ ) 



■C Create ablockidl . > 
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c < Give ablockidl the dotted line style > 

c -C with repetition factor = 5. > 

call gm_$ablock_set_draw_style 

+ ( ablockidl 

+ , gm_$dotted 

+ . int2(5) 

+ . pattern 

+ , int2(0) 

+ . status 

+ ) 

c < Assign ablockidl to aclassidl in viewport 1 . > 

call gm_$ablock_assign_viewport 
+ ( aclassidl 
+ , vpidl 
+ . ablockidl 
+ , status 
) 

c -C Create ablockid2. > 

call gm_$ablock_create 
+ ( int2(l) 
+ , ablockid2 
+ . status 
+ ) 

c < Give ablockid2 the dotted line style > 

c "C with repetition factor = 10. > 

call gin_$ablock_set_draw_style 

+ ( ablockid2 

+ , gm_$dotted 

+ . int2(10) 

+ . pattern 

+ , int2(0) 

+ , status 

+ ) 

c -C Assign ablockidl to aclassid2 in viewport 2. > 

call gm_$ablock_assign_viewport 
+ ( aclassidl 
+ . vpid2 
+ , ablockid2 
+ , status 
+ ) 

c < Create ablockidS. > 

call gm_$ablock_create 
+ ( int2(i) 
+ , ablockidS 
+ . status 
) 

c < Give ablockidS the dotted line style. > 

c -C with repetition factor = 20 > 

call gni_$ablock_set_draw_style 

+ ( ablockidS 

+ , gm_$dotted 

+ . int2(20) 

+ , pattern 
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, int2C0) 
, status 
) 



{ Assign ablockidS to aclassidl in viewport 3. > 
call gni_$ablock_assign__viewport 
( aclassidl 





+ 


, vpid3 




+ 


, ablockidS 




+ 


. status 




+ 


) 


c 






c 








call 


gm_$display_refresh 




+ 


( status 




+ 


) 



< Refresh display to see the effects of } 
< the attribute blocks . > 



call time_$wait 
+ ( time_$relative 
+ , pause 
+ , status 
-f ) 



call gm_$segment_create 
+ ( 'new' 
+ . int2(3) 
+ , sid3 
+ . status 
+ ) 



{ Create 'new' segment. > 



ptiCl) = 

ptl(2) = 

pt2(l) = 10 

pt2(2) = 10 



call gm_$rectangle_16 
+ ( ptl 
+ , pt2 
+ , .FALSE. 
+ . status 
) 



{ Add a rectangle to 'new' segment. > 



call gm_$aclass 
+ ( aclassid2 
+ , status 
) 



< Add an aclass command to 'new' segment. } 



pti(l) = 20 
pt2(l) = 30 



call gm_$rectangle_16 
( ptl 
. pt2 
, .FALSE. 



{ Add a rectangle to 'new' segment. > 
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+ , status 

+ ) 

c { Close 'new' segment. } 

call gm_$segment_close 

+ ( . TRUE . 

+ , status 

+ ) 

c { Create ablockid4. > 

call gni_$ablock_create 

+ ( int2Cl) 

+ , ablockid4 

+ . status 

+ ) 

c { Give ablockid4 the dotted line style } 

c •{ with repetition factor = 30 . > 

call gm_$abloclc_set_dra¥_style 

-^ ( ablockid4 

+ , gm_$dotted 

+ . int2C30) 

+ , pattern 

+ . int2(0) 

+ . status 

+ ) 

c < Assign ablockld4 to aclassid2 in viewport 1. > 

call gni_$ablock_assign_viewport 

+ ( aclassid2 





+ 

+ 
+ 
+ 




. ¥pidl 
, ablockld4 
. status 
) 


c 


c 

+ 

+ 
+ 


all 


gm_$ablock_create 
( int2(l) 
, ablockldS 
. status 
) 


c 








c 









< Create ablockidS. } 



< Give ablockidS the dotted line style } 
■{ with repetition factor = 40. } 
call gm_$ablock_set_draw_style 
+ ( ablockidS 
+ , gm_$ dotted 
+ . Int2 (40) 
+ , pattern 
+ , int2(0) 
+ , status 
+ ) 

< Assign ablockidS to aclassid2 in viewport 2. } 
call gm_$ablock_asslgn_viewport 
+ ( aclassld2 
+ . vpid2 
+ , ablockidS 
■f , status 
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{ Create ablockidS . } 





call 


gin_$ ab 1 o clc_cr e a t e 




+ 


( iiit2(l) 




+ 


, ablockide 




+ 


. status 




+ 


) 


c 






c 







< Give ablockide the dotted line style } 
< with repetition factor = 50 . > 
call gm_$ablock_set_draw_style 
+ ( ablockid6 
-t- . gm_$dotted 
+ , int2(50) 
+ . pattern 
+ , int2(0) 
+ , status 
+ ) 



■C Assign ablockide to aclassid2 in viewport 3. } 
call gm_$ablock_assign_viewport 
+ ( aclassid2 
+ . vpidS 
+ . ablockide 
+ . status 
) 



call gin_$display_segment 
+ ( sid3 
+ . status 
) 



call gm_$viewport_select 
+ ( vpid2 
+ , status 
+ ) 



■C Display 'new' segment in viewport 1. } 



< Select viewport 2. } 



call gm_$display_segment 
+ ( sidS 
+ . status 
+ ) 



{ Display 'new' segment in viewport 2. > 



call gm_$viewport_select 
+ ( vpidS 
+ , status 
+ ) 



< Select viewport 3. > 



call gm_$display_segment 
+ ( sid3 
+ . status 
) 



< Display 'new' segment in viewport 3. > 



call time $wait 
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( time_$relative 
, pause 



status 



) 



call gm_$file_clos< 
+ ( .TRUE. 
+ . status 
) 



< Close the file. } 



call gm_$ terminate 
( status 
) 



{ Terminate the 2D GMR package . } 



END 
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Program with Advanced Viewing Techniques 

The following program changes the color map values; assigns a plane mask to viewports; displays 
a grid; changes the plane mask; assigns viewport background values; displays segments in more 
than one viewport; closes the file; and terminates the package (see Section 14.3). 

PROGRAM courses 

%INCLUDE ' /sys/ins/base . ins . f tn ' 

%INCLUDE ' /sys/ins/time . ins . f tn ' 

^INCLUDE Vsys/ins/gmr .ins.ftn' 

%INCLUDE '/sys/ins/pfm. ins.ftn' 



integer*2 
integer*2 
integer*2 



gm_default_aclass 

repeats 

space 



integer*2 

integer*2 

real 

integer*2 

integer*2 

integer*2 



t)itmap_size(2) 

st 

b(4) 

vpi(i2 

vpidS 

vpid4 



integer*2 

integer*2 

integer*2 

lnteger*2 

real 

integer*2 

integer*4 

lnteger*4 

integer*4 

integer*4 

integer*2 

integer*2 

integer*2 

real 



ablockid 

k 

m 

n 

color_array (8 : 15) 

f ile_id 

sidl 

sid2 

sid3 

sid4 

ptl(2) 

pt2(2) 

transl(2) 

rtransl(2) 



gm_default_aclass = 1 
repeats = 10 

space = 25 

bitmap_size(l) = 1024 
bitmap_size(2) = 1024 



call gm_$init 
+ ( gm_$borrow 
+ . streani_$stdout 
+ , bitmap_size 
+ , int2(8) 
+ , st 



{ Initialize the 2D GMR package. } 
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< Create and name a metafile. > 



call 


gm 


_$f ile_create 


+ 


C 


'gmfile' 
lnt2(6) 


+ 




gm $overwrite 


+ 




gm_$lw 


+ 




file_id 


+ 




St 



call gm_$segment_create 
+ ( 'grid' 
+ . int2(4) 
+ , sidl 
+ , St 
+ ) 



•C Create segment 'grid. " > 



< 'Grid' points are zero-sized rectangles. > 
ptl(l) = 
Do 100 m = 1,8 

ptl(l) = ptl(l) + 100 

ptl(2) = 

Do 50 n = 1,8 

ptl(2) = ptl(2) + 100 
call gm_$rectangle_16 
( ptl 



. ptl 

. .FALSE. 

, St 
) 



50 


continue 


100 


continue 


c 






call gm $segment close 




+ ( .TRUE. 




+ , St 




+ ) 




b(l) = 0.0 




b(2) = 0.0 




b(3) = 0.49 




b(4) = 0.49 



call gm_$viewport_set_bounds 
+ ( b 
+ . st 
+ ) 

b(l) = 0.51 
b(2) = 0.0 
b(3) = 1.0 
b(4) = 0.49 

call gm_$viewport_create 
+ ( b 



{ Close segment 'grid.' } 



■C Shrink viewport 1 . > 



< Create viewport 2. > 
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+ 


, vpid2 


+ 


, St 


+ 


) 


bCl) 


= 0.0 


b(2) 


= 0.51 


b(3) 


= 0.49 


b(4) 


= 1.0 



■C Create viewport 4. } 



c -C Create viewport 3 . > 

call gm_$viewport_create 
+ ( b 
+ , vpidS 
+ , St 
+ ) 

b(l) = 0.51 

b(2) = 0.51 

b(3) = 1.0 

b(4) = 1.0 
c 

call gm_$viewport_oreate 
+ ( b 
+ . vpid4 
+ , St 
) 

c { Red + green = yellow. > 

c FOR k = 8 TO 15 
c DO WITH color_array[ k ] 
c DO BEGIN 
c red =1.0 

c green =1.0 

c blue =0.0 

c END> 

c 

c < Set color values 8 to 15 to yellow. > 

call gm_$display_set_color_map 

+ ( int4(8) 

+ . int2(8) 

+ . color_array 

+ . St 
) 

c < Create an ablock. > 

call gm_$ablock_create 
+ ( int2(l) 
+ , ablockid 
+ . st 
) 

c { For the ablock. set the draw value to 9 . > 

call gm_$ablock_set_draw_value 

+ ( ablockid 

+ , int4(9) 

+ , st 

+ ) 

c i Assign the ablock to the default aclass . > 

call gm_$ablock_assign_display 
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+ 


( gm__default_aclass 


+ 


. ablockld 


-}- 


, St 



call gm_$display_f lie 
( St 
) 



call wait 



call gm__$abloclc_copy 
+ ( iiit2(l) 

+ . ablockld 

+ , St 



{ Display 'grid' in viewport 4. > 

< Wait a moment . > 
< Reset the ablock to default attributes. > 



) 



< For the ablock pass the number 7 . This turns the > 
< first three bits on in the word. Each bit corresponds } 

■C to a plane . > 



call gm_$ablock_set_plane_mask 
+ ( ablockid 
+ . . TRUE . 
+ , int2(7) 
+ , St 
+ ) 



call gm_$segment_create 
+ C 'box' 
-!- , int2(3) 

+ , sid2 
+ , St 

+ ) 

ptl(l) = 
ptl(2) = 

pt2(l) = 10 
pt2(2) = 10 

call gm_$rectaagle_16 
+ ( ptl 
+ , pt2 
+ , . FALSE , 
+ , St 

) 



call gm__$segment_close 
+ ( . TRUE . 
+ , St 
) 



call gm_$segment_create 
( 'row' 



< Create segment 'box. ' > 



< Add a rectangle to 'box. ' > 



i Close segment 'box. ' > 



{ Create segment 'row. * > 
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, int2(3) 

, sidS 

. St 
) 



< Instance segment 'box' into segment 'row. ' > 



200 



transl(l) = 
transl(2) = 
DO 200 k = 1, repeats 

transl(l) = transl(l) + space 
call gm_$instance_translate_2dl6 
+ ( sid2 

■4- , transl 

+ , St 

) 
continue 



< Close segment 'row. ' } 



call gm_$segment_close 
+ ( .TRUE. 
+ . St 
+ ) 



call gm_$segment_create 
+ ( 'block' 
+ , int2(5) 
+ . sid4 
+ , St 
+ ) 



< Create segment 'block. ' > 



< Instance segment 'row' into segment 'block.' > 



300 



transl (2) = 50 
DO 300 k = 1. repeats 
transl (i) = k 

transl (2) = transl (2) - space 
call gm_$instance_translate_2dl6 
+ ( sid3 

+ , transl 

+ . St 

+ ) 

continue 



call gm_$segment_close 
+ ( .TRUE. 
+ , St 
) 



call gm_$display_segment 
+ ( sid4 
+ , St 
+ ) 



< Close segment 'block. ' > 



■C Display segment 'block' in viewport 3. > 



< Wait a moment . > 



call wait 
rtransl(l) =0.5 
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rtransl(2) =1.0 
c < For viewport 3, zoom out. > 

call gm_$¥lew_scale 
+ (0.25 
+ . rtransl 
+ . St 
) 

rtransl (1) = -0.06 
rtransl (2) =0.0 
DO 400 Ic = 1,5 
c { For viewport 3, pan from left to right. > 

call gm_$vie¥_translate 
+ ( rtransl 
+ . St 
) 
400 continue 

rtransl (1) =0.5 
rtransl (2) =0.5 
DO 500 k = 1,5 
c < For viewport 3, pan diagonally towards lower left. > 

call gm_$view_scale 
+ (0.85 
+ . rtransl 
+ . St 
) 
500 continue 

c { Wait a moment . > 

call wait 
c { For viewport 2, set the background value to 2 . > 

call gm_$viewport_set_background_valu 
+ ( vpid2 
+ , int4(2) 

+ . st 
) 

c < Select viewport 2. > 

call gm_$vie¥port_select 
H- ( vpid2 
+ . St 
) 

c -C Display segment 'row' in viewport 2. > 

call gm_$display__segment 
+ ( sid3 
+ . st 
) 

c ■( Wait a moment . > 

call wait 

c { For viewport 3, set background value to 2 . > 

call gm_$viewport_set_background_valu 

+ ( vpidS 

+ , int4(3) 

+ , st 
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call gm_$viewport_selecl; 
+ ( vpidS 
+ . St 
+ ) 



call gm_$display_segment 
+ ( sid4 
+ , St 
+ ) 



•C Select viewport 3. > 



•C Display segment 'block' in viewport 3. > 



call wait 



call gm_$file_close 
+ ( .TRUE. 

+ . st 
+ ) 



call gin_$ terminate 
+ ( St 
+ ) 



< Wait a moment. > 
■C Close the file. } 



i Terminate the 2D GMR package . > 



END 

subroutine check 
+ ( Status 
) 
integer*4 



Status 



IF (status .ne. 0)THEN 

call pf m_$error_trap ( status ) 

END IF 

return 
end 



subroutine wait 

integer*2 
integer*4 



pause (3) 
status 



pause (1) = 

pause (2) = 20 

pause (3) = 

< Wait five seconds. > 
call time_$wait 
+ ( time_$relative 

+ , pause 

+ , status 

) 

call check ( status ) 

END 
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Attributes and Instancing 



The following program displays a file as it is being created and edited, 
picture in Figure D-1. 



The file creates the 



PROGRAM hotel 

%INCLUDE Vsys/ins/base.ins.ftn* 

%INCLUDE • /sys/ins/error . ins . f tn ' 

%INCLUDE '/sys/ins/pfm.ins.ftn' 

^INCLUDE ' /sys/lns/gmr . ins . f tn ' 

%INCLUDE Vsys/ins/time.ins.ftn' 



lnteger*4 
integer*2 
integer*2 
integer*4 
integer*4 
integer*4 
integer*4 
integer*4 
integer*4 
character 
integer*2 
integer*2 
integer*2 
integer*2 
integer*2 
integer*2 
integer*2 
integer*2 



status 

f ile_i<i 

font_file_id 

sld_scene 

sid_door 

sid_¥indow 

sid_sign 

sid_tree 

sid_house 

pattern (8) 

p(12) 

q(10) 

center (2) 

radius 

i 

pause (3) 

corner 1 (2) , corner2C2) 

bitmap_size(2) 



bitmap_size(l) = 1024 

bitmap_size(2) = 1024 

call GM_$INIT 
H ( gni_$direct 
H , stream_$stdout 
I- , bitmap_size 
H , int2(8) 
I- , status 
^ ) 

call check(status) 



"C Intialize 2D GMR package . > 



-C Create and name a metafile. > 



call GM_$FILE_CREATE 

( ' hotel. gm' 

. int2(8) 

, gm_$overwrite 

, gm_$l¥ 

, file_id 

, status 

) 
call check(status) 
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-C Load a font family. > 



call GM_$F0NT_FAMILY_includ6 
H- ( 'font_families ' 
+ , int2(13) 
^- , gm_$pixel 
+ , font_file_id 
+ . status 
+ ) 

call check (status) 



call GM_$DATA_COERCE_SET_REAL 
^ ( gm_$32 

. status 

) 
call check (status) 



call GM_$SEGMENT_CREATE 
( " 
+ . Int2(0) 
+ . sid_door 
+ . status 
) 
call check(status) 



< Set the data coerce. > 



{ Create the segment for the door. > 



•{ Construct the door. > 



cornerl(l) = 

cornerl(2) = 

corner2(l) = 36 

corner2(2) = 80 

call GM_$RECTANGLE_16 
+ ( cornerl 
+ . corner2 
+ , . TRUE . 
-I- , Status 
) 

call check(status) 

call GM_$FILL_VALUE 
+ ( int4(0) 
-»- , status 
+ ) 

call check (status) 

cornerl(l) = 30 

cornerl (2) = 38 

corner2(l) = 33 

corner2(2) = 41 

call GM_$RECTANGLE_16 
+ ( cornerl 

+ , corner2 
+ , . TRUE . 
+ , status 
) 

call check(status) 



{ Construct the door knob . } 
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call GM_$SEGMENT_CLOSE 
+ ( .TRUE. 
+ , status 
+ ) 

call clieclc (status) 



call GM_$SEGMENT_CREATE 
+ ( •• 

+ , int2(0) 

+ , sid_winclow 

+ , status 

+ ) 

call check (status) 

cornerl(l) = 

cornerl(2) = 

corner2(l) = 36 

corner2(2) = 36 

call GM_$RECTANGL£_16 
+ ( cornerl 
+ , corner2 
+ , . FALSE . 
+ , status 

) 
call check (status) 



p(l) 

P(2) 
p(3) 
p(4) 
call 


= 
= 18 
= 36 
= 18 

GM_$P0LYLINE_2D 1 6 
( lnt2(2) 




^ P 

, .FALSE. 




. . FALSE . 




, status 



) 

call check (status) 



p( 1 

p( 2 
p( 3 
p( 4 
call 
+ 


) = 18 
) = 
) = 18 
) = 36 

GM_$P0LYLINE_2D 1 6 
( lnt2(2) 


+ 
+ 


' P 

. .FALSE. 


+ 


, .FALSE. 


+ 


, status 


+ 
call 


) 
check(status) 


call 


GM $SEGMENT_CLOSE 


+ 


( .TRUE. 


+ 


, status 


call 


) 
check (status) 



< Create the segment for the window. } 
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< Create the segment for the sign. > 



call 


GM $SEGMENT CREATE 


+ 


( •• 


+ 


, int2(0) 


+ 


, sid_slgn 


+ 


. status 


+ 


) 


call 


check (status) 


call 


GM_$TEXT_SIZE 


+ 


(14.0 


+ 


, status 


+ 


) 


call 


check (status) 


P( 1 


) = 


p( 2 


) = 


call 


GM $TKXT 2D 16 


+ 


( P 


+ 


, 0.0 


+ 


. 'GRAND MOTEL' 


+ 


, int2(ll) 


+ 


, status 
) 
check (status) 


"4" 

call 


call 


GM_$SEGMENT_CLOSE 


+ 


( .TRUE. 


+ 


. status 


+ 


) 


call 


check (status) 



call GM $SEGMENT CREATE 



( 



) 



int2(o) 

sid_house 

status 



call check(status) 



cornerK 1 ) = 
cornerK 2 ) = 
corner2( I ) = 480 
corner2( 2 ) = 260 
call GM_$RECTANGLE_16 

+ ( cornerl 

+ , corner2 

+ . .FALSE. 

+ . status 

+ ) 
call check (status) 



p(l) = -10 

p(2) = 255 

p(3) = 240 

p(4) = 380 



< Create the segment for the house . > 



i Build the house . > 



< Build the roof. } 



FORTRAN Program Examples 



F-30 



p(5) = 490 
p(6) = 255 



call GM_$P0LYLINE_2D16 
+ ( lnt2(3) 

+ . P 
+ , . FALSE . 
+ , . FALSE . 
+ , status 
) 
call check(status) 



p(l) = 300 

p(2) = 350 

p(3) = 300 

p(4) = 370 

p(5) = 330 

p(6) = 370 

p(7) = 330 

p(8) = 335 

call GM_$F0LYLINE_2D16 

V ( lnt2(4) 

^ ' P 

I- , .FALSE. 

!- , . FALSE . 

y . status 

^ ) 

call check (status) 



< Build the chimney. } 



{ Build the round window. > 



center (1) = 240 
center (2) = 195 
radius = 45 

call GM_$CIRCLE_16 
I- ( center 
y , radius 

y , .FALSE. 

I- . status 
) 

call check (status) 



p(l) 


= center(l) - 


radius 


p(2) 


= center (2) 




p(3) 


= center(l) 




p(4) 


= center (2) + 


radius 


p(5) 


= center(l) + 


radius 


p(6) 


= center (2) 




p(7) 


= center(l) 




p(8) 


= center (2) - 


radius 


call 


CM $POLYLINE_ 


2D16 


+ 


( int2(4) 




+ 


. p 




+ 


, . TRUE . 




+ 


, . FALSE . 




+ 


, Status 





{ Draw rectangle inside window. > 
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-C Draw horizontal line inside window. > 



) 
call check(status) 

p( 1 ) = center (i) - radius 

p( 2 ) = center (2) 

p( 3 ) = center (1) + radius 

p( 4 ) = center (2) 



call GM_$P0LYLINE_2D16 
( int2(2) 

' P 

. . FALSE . 
. .FALSE. 
. status 
) 
call checK: (status) 

p( 1 ) = center(l) 

p( 2 ) = center (2) + radius 

p( 3 ) = center(l) 

p( 4 ) = center (2) - radius 



call GM_$P0LYLINE_2D16 
+ ( int2(2) 
+ , p 
+ , . FALSE . 
+ , . FALSE . 
+ , status 
) 

call checkCstatus) 

< Instance and position the door. > 
q( 1 ) = 222 
q( 2 ) = 

call GM_$INSTANCE_TRANSLATE_2D16 
+ ( sid_door 
+ . q 
+ , status 
) 
call check(status) 

< Instance and position the windows. > 
q( 1 ) = 50 
q( 2 ) = 40 

call GM_$ INSTANCE_TRANSLATE_2D 1 6 
+ ( sid_¥indow 
+ , q 
+ , status 
) 
call check(status) 

q( 1 ) = 118 

call GM_$INSTANCE_TRANSLATE_2D16 
+ ( sid_¥indo¥ 
+ , q 
+ . status 
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+ ) 
call check (status) 

q( 1 ) = 326 

call GM_$INSTANCE_TRANSLATE_2D16 
+ ( sid_window 
+ . q 
+ , status 
+ ) 

call check (status) 

q( 1 ) = 394 

call GM_$INSTANCE_TRANSLATE_2D16 
+ ( sid_window 
+ , q 
+ , status 
) 

q( 2 ) = 180 

call GM_$INSTANCE_TRANSLATE_2D16 
+ ( sid_wlndow 
+ , q 
+ , status 
+ ) 

q( 1 ) = 326 

call GM_$ INSTANCE_TRANSLATE_2D 1 6 
+ ( sid_window 

+ . q 

+ , status 

+ ) 

call check (status) 

q( 1 ) = 118 

call GM__$INSTANCE_TRANSLATE_2D16 
+ ( sid_¥indow 

+ . q 

+ , status 

+ ) 
call check(status) 

q( 1 ) = 50 

call GM_$INSTANCE_TRANSLATE_2D16 

+ ( sid_¥indow 

-}■ , q 

+ , status 

+ ) 

call check(status) 



{ Instance and position the segment for the sign. > 



q( 1 ) = 172 

q( 2 ) = 120 

call GM_$INSTANCE_TRANSLATE_2D16 
+ ( sld_sign 
+ , q 
+ , status 
) 

call check(status) 
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call 


GM_$SEGMENT CLOSE 


+ 


( .TRUE. 


+ 


, status 


+ 


) 


call 


check (status) 


call 


GM $SEGMENT CREATE 


+ 


( " 


+ 


, 


+ 


, si(i_tree 


+ 


. status 


+ 


) 


call 


check (status) 


P( 1 


) = 


p( 2 


) = 


pC 3 


) = 


p( 4 


) = 150 


call 


GM_$P0LYLINE_2D 1 6 


+ 


( iiit2(2) 


+ 


' P 


+ 


, .FALSE. 


+ 


. .FALSE. 


+ 


, status 



■C Create the segment for the trees. > 



) 
call check (status) 



P( 1 


) = 12 


p( 3 


) = 12 


call 


GM_$F0LYLINE_2D 1 6 


+ 


( int2(2) 


+ 


' P 


+ 


, .FALSE. 


+ 


, .FALSE. 


+ 


, status 


+ 


) 


call 


check(status) 


P( 1 


) = 6 


p( 2 


) = 200 


call 


GM $CIRCLE 16 


+ 


( P 


+ 


. int2(50) 


+ 


. . FALSE . 


+ 


. status 


+ 


) 


call 


check (status) 


call 


GM_$DRAW_STYLE 


+ 


( gm_$dotted 


+ 


. int2(2) 


+ 


. pattern 


+ 


, int2(0) 


+ 


. status 


+ 


) 


P( 1 


) = 


p( 2 


) = 180 
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p( 3 


) = -40 




p( 4 


) = 200 




call 


GM_$POLYLINE_ 


2D 16 


+ 


( int2(2) 




+ 


' P 




+ 


. .FALSE. 




+ 


. .FALSE. 




+ 


, status 




+ 


) 




P( 1 


) = 12 




p( 3 


) = 52 




call 


GM $POLYLINE 


2D 16 


+ 


( int2(2) 




+ 


• P 




+ 


, .FALSE. 




+ 


, .FALSE. 




+ 


, status 




+ 


) 




call 


check (status) 




P( 1 


) = 4 




p( 2 


) = 190 




p( 3 


) = -20 




p( 4 


) = 230 




call 


GM_$POLYLINE 


2D 16 


+ 


C int2(2) 




+ 


' P 




+ 


, .FALSE. 




+ 


. .FALSE. 




+ 


. Status 




+ 


) 




call 


check (status) 




P( 1 


) = 8 




p( 2 


) = 190 




p( 3 


) = 32 




p( 4 


) = 230 




call 


GM $POLYLINE 


2D 16 


+ 


( lnt2(2) 




+ 


' P 




+ 


. .FALSE. 




+ 


, .FALSE. 




+ 


, Status 




+ 


) 




call 


check (status) 




P( 1 


) = 6 




p( 2 


) = 195 




p( 3 


) = 6 




p( 4 


) = 240 




call 


GM_$POLYLINE_ 


2D 16 


+ 


( int2(2) 




+ 


' P 




+ 


, .FALSE. 




+ 


. . FALSE . 




+ 


, status 





) 

call check (status) 
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p( 1 


) = 


p( 2 


) = 170 


p( 3 


) = 


p( 4 


) = 150 


call 


GM_$P0LYLINE_2D 1 6 


+ 


( iiit2(2) 


+ 


. P 


+ 


. .FALSE. 


+ 


. .FALSE. 


+ 


. status 


+ 


) 


call 


check (status) 


P( 1 


) = 12 


p( 3 


) = 12 


call 


GM_$P0LYLINE_2D 1 6 


+ 


( int2(2) 


+ 


' P 


+ 


. .FALSE. 


+ 


, .FALSE. 


+ 


. Status 


+ 


) 


call 


check (status) 


call 


GM_$SEGMENT_CLOSE 


+ 


( .TRUE. 


+ 


. status 


+ 


) 


call 


check (status) 


call 


GM $SEGMENT CREATE 


+ 


( " 


+ 


. int2(0) 


+ 


, si(i_scene 


+ 


. status 



) 

call check(status) 



< Create the segment called scene . > 



< Instance the segment for the house . > 



p( 1 

p( 2 

call 
+ 


) = 
) = 

GM_$INSTANCE_TRANSLATE_2D1 6 
( sid_house 




+ 
+ 
+ 
call 


' P 

. status 

) 
check (status) 




P( 1 
p( 2 
call 

+ 

+ 


■C Instance, translate, and scale the segment for the trees. 
) = -85 
) = -25 
GM $ INSTANCE SCAT.K 2D 16 

( Sid tree 

. 2.0 


> 


+ 
+ 
+ 


. P 

. status 

) 
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p( 1 ) = 530 

p( 2 ) = 55 

call GM_$INSTANCE_SCALE_2D16 
+ ( sid_tree 
+ .0.75 

+ ' P 
+ , status 
+ ) 
call check (status) 

p( 1 ) = 610 

p( 2 ) =105 

call GM_$INSTANCE_SCALE_2D16 
+ ( sid_tree 
+ .0.85 

+ ' P 

+ , status 

) 
call check (status) 

call GM_$SEGMENT_CLOSE 
+ ( .TRUE. 
+ . status 
) 

call check(status) 



call GM_$DISPLAY_SEGMENT 
+ ( sid_scene 
+ . status 
) 

call check (status) 



pause (1) = 

pause (2) = 20 

pause (3) = 

call TIME_$WAIT 
+ ( time_$relatlve 
+ . pause 
+ . status 
+ ) 

call check(status) 



call GM_$FILE_CLOSE 
+ ( .TRUE. 
+ , status 
) 

call check(status) 



< Now display the completed scene . > 



< Admire the scene for five seconds . > 



< Close and save the file. > 



call GM_$TERMINATE 
+ ( status 
+ ) 

call check(status) 



{ Terminate the GMR package . } 



END 
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subroutine check (status) 
integer*4 status 

%lnclud,e '/sys/ins/base . ins .f tn' 
^include Vsys/ins/pfm. ins . f tn' 



IF (status .ne. 0)then 

call pfm_$error_trap (status) 

endif 

return 

end 
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2D GMR program 3-1 

Architectural application 2-3 
Attribute 1-2, 5-1, 13-1, 13-5, 13-6 

and instancing 5-5 

block 13-1, 13-6 

class 13-1, 13-5, 13-6 

command 1-3, 3-1, 5-1, 13-5 

default settings 5- 1 

draw 5- 1 

fill 5-1 

GM bitmap 13-6 

instancing 5- 1 

line style 5-1 

plane mask 5-1 

precedence 5-1 

procedures 13-7 

raster operation 5-3 

techniques 13-7 

terminology 13- 1 

viewing 13-6 
Attribute block 3-5, 12-8, 13-2, 13-4, 13-6 

assigning viewport 13-6 

copying 13-4 

creating 13-2, 13-3 

defined 13-3 

display 11-1 

GPR- specific 3-5 

identifying 13-3 

modifying 13-3 

no- change value 13-4 

reading 13-4 
Attribute blocks 11-1 
Attribute classes 12-8 
Attribute commands 

and precedence 5-1 
Attributes 5-1, 5-2, 5-5, 13-6 

Background 

See also Attribute 
Background value 5-2, 14-5 
Binary exponent 7-3, 7-4 
Bitmap 1-1, 1-5, 2-1, 3-4, 8-1 
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display 3"'4 

GM 8-1 

graphics primitives 2-2, 3-4 

main- memory 3-4 

pixels 8- 1 

planes 8- 1 

size 8- 1 
See also GM bitmap 
Border 8-4 
Borrow mode 2-2, 2-3, 3-4, 4-2, 11-1 

C example E-1, E-3, E-6, E-9, E-11, E-22, E-30, E-36, E-43 
Character 6-7 

default values 6-8 

height 6-8 

offset 6-8 

size 6-8 

stroke font 6-7 

width 6-7 
Characteristics 

See also Attribute 
Circle 1-2, 1-3, 4-1, 5-5 
Color map 5-2, 14-1, 14-6, 15-3, E-36, F-19 

4- plane display 14-2 

8- plane display 14-2 

and mode 14-4 

changing 14-4 

default 14-4 

defined 14- 1 

index 14-2 

intensity 14-1 

on color nodes 15-3 
Color value 14-1 
Command 1-2, 1-3 

attribute 1-3 

defined 1-3 

instance 1-3 

primitive 1-3 

tag 1-3 
Command line parser 15- 1 
Comment 1-3, 15-1 

See also Tag commands. Tags 
Compacting files 15-3 
Coordinate data 1-6 
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16- bit integers 1-6 

32- bit integers 1-6 

Single- precision real numbers 1- 
Coordinate data types 7-3 

coercing 7-3 

groups of 7-3 

storing 7-3 
Coordinate system 2-5, 8-1, 15-4 

2D GMR 15-4 

bitmap 8- 1 

current position 15-4 

defined point 15-4 

GPR 15-4 

pixel 8- 1 

segment 8- 1 
Coordinates 6- 1 

segment 6-1 
Copying 10-13 

instancing 10-13 

segment 10-13 
See also Editing 
Core graphics 1-7, 15-5 
Current position 15-5 
Current segment 3-7 
Cursor 10-3 

activating 10-3 

pattern 10-3 

position 10-3 
Curve 4-1 

Data 1-2 

graphic 1-2 

nongraphic 1-2 
Data types 1-2, 7-3, 7-4 

16- bit integer 7-3, 7-4 

32- bit integer 7-3, 7-4 

coercing 7-4 

coordinate 7-3 

mixing 7-4 

precision 7-4 

real 7-3 

real variables 7-4 

storing 7-4 
Defined points 15-5 
Device independence 2-6 
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Device"independence 1-4, 1-8 
Direct mode 2-2, 3-4, 4-2, 11-1 
Display 3-1, 3-2, 3-4, 4-2, 10-2, 15-3 

acquiring 15-3 

characteristics 1-2 

configuration 8-1 

file 3-2 

hardware 8- 1 

modes 2-2, 3-3, 11-1 

refreshing 10-2 

releasing 15-3 

retaining control of 3-4 
Display coordinates 8-2 
Display Manager 3-4 
Display modes 2-2, 3-3, 4-2, 8-2, 11-1 

borrow 3-3 

direct 3-3 

main- bitmap 3-3 

no- bitmap 3-3 

within- GPR 3-3 
Display techniques 13-15 
Displaying 4-2, 4-3, 8-7 

attribute block 11-1 

attributes 4-2 

current file 4-3, 8-7 

current viewport 4-3, 8-7 

file 4-2 

part of file 4-3, 8-7 

part of segment 4-3, 8-7 

refreshing 8-8 

segment 4-2 

user-defined primitives 11-3 
See also Viewing 
DOMAIN 2D Graphics Metafile Resource 1-8 
DOMAIN Core Graphics 1-8, 15-4 

imaging 15-5 

incremental display 15-5 
DOMAIN graphics packages 1-8 

DOMAIN Graphics Primitives 1-7, 1-8, 2-2, 3-4, 15-4 
DOMAIN system 1-7 
Draw Raster Op 5- 1 
Draw style 5- 1 
Draw value 5-1 
Drawing 1-2 
Drawing attributes 5-1 
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EDFONT 6-6 

Editing 1- 2, 1- 3, 3- 1, lO- 10 

erasing 10" 13 

highlighting a command 10-11 

inserting a command 10-11 

picking 10- 13 

picking a command 10-11 
Erasing 10-13 
Event reporting 10-5 
Event types 10-4 

button 10-4 

keystroke 10-4 

locator 10-4 

locator stop 10-4 

window transition 10-4 
Ebcternal file 1-3 
External file format 12-1 

Fault handlers 15-4 
Files 3-5 

closing 3-5 

creating 3-5 

editing 3-5 

opening 3-5 

reading 3-5 

selecting 3-5 
Fill background value 5-1 
Fill pattern 5-1 
Fill value 5-1 
Filling 1-2, 5-2 

background 5-2 

pattern 5-2 

value 5-2 
Filling attributes 5-1 
Font 6-1 

editing 6-6 

family 6-1 

file 6-1 

stroke 6-7 
Font family 6-2 

excluding 6-2 

file 6-2 

identifying 6-2 

including 6-2 

limitations 6-8 
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renaming 6~2 

using 6~2 
Font family file 6-2, 6-3 

editing 6-6 

example 6-2 

renaming 6-3 

stroke 6-6 
Font family ID number 5- 1 
Fonts 6-3 
FORTRAN example F- 1, F-7, F- 10, F- 19, F- 26 

GM bitmap 2-3, 8-1, 8-4, 8-8, 13-6 
GM_$ABLOCK_ASSIGN_DISPLAY 13-6 
GM_$ABLOCK_ASSIGN_VIEWPORT 13-6 
GM_$ABLOCK_COPY 13-4 
GM_$ABLOCK_ CREATE 13-2 
GM_ $ABLOCK_INQ _ ASSIGN_DISPLAY 13- 6 
GM_$ABLOCK_INQ_ASSIGN_VIEWPORT 13-6 
GM_$ABLOCK_INQ_DRAW_RASTER_OP 13-4 
GM_$ABLOCK_INQ_DRAW_STYLE 13-4 
GM_$ABLOCK_INQ_DRAW_ VALUE 13-4 
GM_$ABLOCK_INQ_FILL_PATTERN 13-4 
GM_$ABLOCK_INQ_FILL_VALUE 13-4 
GM_$ABLOCK_INQ_FONT_FAMILY 13-4 
GM_$ABLOCK_INQ_PLANE_MASK 13-4 
GM_$ABLOCK_INQ_TEXT_BACKGROUND_VALUE 13-4 
GM_$ABLOCK_INQ_TEXT_SIZE 13-4 
GM_$ABLOCK_INQ_TEXT_VALUE 13-4 
GM_$ABLOCK_SET_DRAW_RASTER_OP 13-3 
GM_$ABLOCK_SET_DRAW_STYLE 13-3 
GM_$ABLOCK_SET_DRAW_VALUE 13-3 
GM_$ABLOCK_SET_Fn.L_PATTERN 13-3 
GM_$ABLOCK_SET_FILL_VALUE 13-3 
GM_$ABLOCK_SET_FONT_FAMILY 13-3 
GM_$ABLOCK_SET_PLANE_MASK 13-3 
GM_$ABLOCK_SET_TEXT_BACkGROUND_VALUE 13-3 
GM_$ABLOCK_SET_TEXT_SIZE 13-3 
GM_$ABLOCK_SET_TEXT_VALUE 13-3 
GM_$ACLASS 13-1 
GM_$CIRCLE_[16,32,REAL] 4-1 
GM_$C0MMA1W_DELETB 10-13 
GM_$C00RD_BITMAP_T0_SEG_2D 8-1 
GM_$C00RD_PIXEL_T0_SEG_2D 8-1 
GM_$COORD_SEG_TO_BITMAP_2D 8-1 
GM $COORD SEG TO PIXEL 2D 8-1 
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GM_$CURSOR_INQ_ACTIVE 10-3 
GM_$CURSOR_INQ__PATTERN 10-3 
GM_$CURSOR_INQ_POSITION 10-3 
GM_$CURSOR_SET_ACTIVE 10-3 
GM_$CURSOR_SET_PATTERN 10-3 
GM_$CURSOR_SET_POSITION 10-3 
GM_$CURVE_2D[l6,32,REALj 4-1 
GM_$DATA_COERCE_INQ_REAL 7-3 
GM_$DATA_COERCE_SET_REAL 7-3 
GM_$DISPLAY_FILE 4-2, 8-6 
GM_$DISPLAY_FILE_PART 4-3, 8-7 
GM_$DISPLAY_INQ_COLOR_MAP 14-5 
GM_$DISPLAY_REFRESH 8-8 
GM_ $DISPLAY_ SEGMENT 4- 2, 8- 6 
GM_$DISPLAY_SEGMENT_GPR_2D 8-6 
GM_$DISPLAY_SEGMENT_PART 4-3, 8-7 
GM_$DISPLAY_SET_COLOR_MAP 14-5 
GM_$DRAW_RASTER_OP 5-3 
GM_$DRAW_ STYLE 5-2 
GM_$DRAW_ VALUE 5-2 
GM_$FILE_CLOSE 3-5 
GM__$FILE_ COMPACT 15-3 
GM_$FILE_ CREATE 3-5 

GM_$FILE_INQ_PRIMARY_SEGMENT 3-7, 7-1 
GM_$FILE_OPEN 3-5 
GM_$FDLE_SELECT 3-5 

GM_$FE.E_SET_PRIMARY_SEGMENT 3-7, 7-1 
GM_$FILL_BACKGROUND_VALUE 5-2 
GM_$FILL_PATTERN 5-2 
GM_$FILL_ VALUE 5-2 
GM_$FONT_FAMDLY 6-2 
GM_$FONT_FAMILY_EXCLUDE 6-2 
GM_$FONT_FAMILY_INCLUDE 6-2 
GM_$FONT_FAMILY_INQ_ID 6-2 
GM_$FONT_FAMILY_RENAME 6-2 
GM_$INIT 3-3 
GM_$INPUT_DISABLE 10-4 
GM_$INPUT_ENABLE 10-4 
GM__$INPUT_EVENT_WAIT 10-5 
GM_$INQ_ACLASS 10-21 
GM_$INQ_BITMAP_SIZE 8-1 
GM_$INQ_CIRCLE_[16,32,REAL1 10-21 
GM_$INQ_COMMAND_TYPE 10-21 
GM_$INQ_CONFIG 8-1 
GM_$INQ_CURVE_2D[16,32,REAL] 10-21 
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GM_$INQ_DRAW_RASTER_OP 10-21 
GM_$INQ_DRAW_STYLE 10-21 
GM_$INQ_DRAW_VALUE 10-21 
GM_$INQ_FILL_BACKGROUND_VALUEE 10-21 
GM_$INQ_FILL_PATTERN 10-21 
GM_$INQ_FILL_VALUE 10-21 
GM_$INQ_FONT_FAMILYY 10-21 
GM_$INQ_INSTANCE_SCALE_2D[16,32,REAL] 10-21 
GM_$INQ_INSTANCE_TRANSFORM_2D[16,32,REAL] 10-21 
GM_$INQ_INSTANCE_TRANSLATE_2D[16,32,REAL] 10-21 
GM_$INQ_PLANE_MASK 10-21 
GM_$INQ_POLYLINE_2D[16,32,REALl 10-21 
GM_$INQ_PRIMITIVE_2D[16,32,REAL] 10-21 
GM_$INQ_RECTANGLE_[16,32,REAL] 10-21 
GM_$INQ_TAG 10-21 
GM_$INQ_TEXT_2D[16,32,REAL] 10-21 
GM_$INQ_TEXT_BACKGROUND_VALUE 10-21 
GM_$INQ_TEXT_SIZE 10-21 
GM_$DvrQ_TEXT_VALUE 10-21 
GM_ $INSTANCE_ SCALE_ 2D [16,32,REAL1 4- 5 
GM_$INSTANCE_TRANSF0RM_2D[16,32,REAL] 4- 10 
GM_ $INSTANCE_TRANSLATE_ 2D [16,32,REAL] 4- 5 
GM_$MODELCMD_INQ_MODE 9-2, 10-1 
GM_$MODELCMD_SET_MODE 9-2, 10-1 
GM_$PICK_ COMMAND 10-10 
GM_$PICK_HIGHLIGHT_COMMAND 10-10 
GM_$PICK_HIGHLIGHT_SEGMENT 10-8 
GM_$PICK_INQ_ CENTER 10-8 
GM_$PICK_INQ_LIST 10-8 
GM_$PICK_INQ_MASK 10-12 
GM_$PICK_INQ_SIZE 10-8 
GM_$PICK_INQ_THRESHOLD 10-12 
GM_$PICK_ SEGMENT 10-8 
GM_$PICK_SET_CENTER 10-8 
GM_$PICK_SET_MASK 10-12 
GM_$PICK_SET_SIZE 10-8 
GM_$PICK_SET_THRESHOLD 10-12 
GM_$PICK_TRANSFORM_POINT 10-8 
GM_$PLANE_MASK 5-2 
GM_$POLYLINE_2D[16,32,REALl 4-1 
GM_$PRIMITIVE_2D[16,32,REAL] 4-1 
GM_$PRIMITIVE_DISPLAY_2D 11-3 
GM_$PRINT_FILE 12-1 
GM_$PRINT_FILE_PART 12-1 
GM_$RECTANGLE_116,32,REAL] 4-1 
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GM_$REFRESH_SET_ENTRY 8-8 
GM_$REPLACE_INQ_FLAG 10-1 
GM_$REPLACE_SET_FLAG 10-1 
GM_$SEGMENT_CLOSE 3-6 
GM_$SEGMENT_COFY 10-13 
GM_$SEGMENT_CREATE 3-6 
GM_$SEGMENT_DELETE 3-6 
GM_$SEGMENT_ERASE 10-13 
GM_$SEGMENT_INQ_COUNT 3-6 
GM_$SEGMENT_INQ_CURRENT 3-6 
GM_$SEGMENT_INQ_ID 3-6 
GM_$SEGMENT_INQ_NAME 3-6 
GM_$SEGMENT_INQ_PICKABLE 7-2 
GM_$SEGMENT_INQ_TEMPORARY 7-2 
GM_$SEGMENT_INQ_VISIBLE 7-2 
GM_$SEGMENT_OFEN 3-6 
GM_$SEGMENT_RENAME 3-6 
GM_$SEGMENT_SET_PICKABLE 7-2 
GM_$SEGMENT_SET_TEMPORARY 7-2 
GM_$SEGMENT_SET_VISIBLE 7-2 
GM_$TAG 15-1 
GM_$TAG_LOCATE 15-1 
GM_$TERMINATE 3-3 
GM_$TEXT_2D[16,32,REAL] 6-1 
GM_$TEXT_BACKGROUND_ VALUE 6-2 
GM_$TEXT_SIZE 6-2 
GM_$TEXT_VALUE 6-2 
GM_$VIEW_ SCALE 8-8 
GM_$VIEW_TRANSFORM 8-8 
GM_$VIEW_TRANSFORM_RESET 8-8 
GM_$VIEW_TRANSLATE 8-8 
GM_$VIEWPORT_ CLEAR 8-4 
GM_$VIEWPORT_ CREATE 8-4 
GM_$VIEWPORT_DELETE 8-4 

GM_$VIEWFORT_INQ_BACKGROUND_VALUE 14-5 
GM_$VIEWPORT_INQ_BORDER_SIZE 8-4 
GM_$VIEWPORT_INQ_BOUNDS 8-4 
GM_$VIEWPORT_INQ_CURRENT 8-4 
GM_$VIEWPORT_INQ_REFRESH_STATE 10-2 
GM_$VIEWPORT_MOVE 8-4 
GM_$VIEWPORT_REFRESH 8-8 
GM_$VIEWPORT_ SELECT 8-4 

GM_ $VIEWPORT_ SET_BACKGROUND _ VALUE 14- 5 
GM_$VIEWPORT_SET_BORDER_SIZE 8-4 
GM IVIEWPORT SET BOUNDS 8-4 
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GM_$VIEWPORT_SET_REFRESH_STATE 10-2 
GM_$VISIBLE_INQ_MASK 8-5 
GM_$VISIBLE_INQ_THRESHOLD 8-5 
GM_$VISIBLE_SET_MASK 8-5 
GM_$VISIBLE_SET_THRESHOLD 8-5 
Graphics application systems 1-7 
Grid 7-3, 14-6, E-36, F-19 

Hard copy 1-2, 1-5 
Hardware 

configuration 8-1 
Hierarchical order of segments 3-2 
Hierarchy 3-2,3-7,7-1 

start of 3-7,7-1 
Highlighting 10-8 

Icon 6-9 

Initializing 2-2, 3-1, 3-3 

Input 1-3, 9-1, 10-1 

devices 9-1, 10-4 

disabling 10-4 

enabling 10-4 
Input devices 1-4 

Instance command 1-3,3-1,3-2,4-3 
Instances 4-5 

rotating 4-3 

scaling 4-3 

transforming 4-5 

translating 4-3, 4-5 
Instancing 1-2, 3-2, 3-7, 5-5, 7-1, 10-8 

and attributes 5-1, 5-5 

picking segments 10-8 

primary segment 3-7, 7-1 
Interactive applications 9-1, 9-3, E"22 

Keyboard 3-4, 10-5 
charts 10-5 
definitions 10- 5 
keys 10-5 

Limitations 

font family 6-8 
Line 5-2 

attributes 5-2 

pixel value 5-2 

style 5-2 
Line drawing 1-2 
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Line style 5-1 

See also Attribute 
Logical devices 1-3 
Long indentifiers 15"3 

Main- bitmap mode 2-2, 3-4, 4-2, 11-1 
Metafile 1-1,3-1 

creating 3- 1 

displaying 3- 1 

editing 3- 1 

opening 3- 1 
Model 1-2 
Modeling 6- 1 
Modeling routines 1-3, 1-6 

drawing and filling 4-1 

instances 4-3 

tags 15-1 

text 6-1 
Mouse 10-4 
Moving, view 2-3 
Multiple copies 3-2 

See also Instancing 

No- bitmap mode 2-2, 3-4 

Optimizing performance 15-2 
Output 11-12 

See also Printing 

Pascal example 3-9, 4-5, 5-6, 6-3, 6-9, 8-9, 9-3, 10-13, 
10-20, 11-4, 13-8, 14-6, 15-1, D-1, E-18 

Pattern 5-2 

Permanence of segment 7-3 

Pickability 7-2 

Picking 1-3, 10-6, 10-8, 10-10, 10-12, 10-13 

and coordinates 10-6 

and pickable mask 7-2, 10-12 

and pickable threshold 7-2, 10-12 

and pickable value 7-2, 10-12 

aperture 10-6 

center 10-6 

command 1-3, 2-4, 10-6, 10-10 

current picked segment 10-8 

instancing 10-8 

listing 10-8 

pick operations 7-2 

routines 2-4 

search rules 10-8 
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segment 1-3, 2-4, 10-6, 10-8 

uses of 10-12 
Picture 3-7,7-1 
Picture data 3-1 
Pixel value 5-2 
Plane 5-1 
Plane mask 5-1, 5-2, 8-6 

mode 8-6 

visibility 8-6 
Planes 15-4 
Polygon 1-2 
Polyline 1-3, 4-1, 7-3 
Precedence 

and attribute commands 5-1 
Precision 7-3, 7-4 

16- bit integer 7-4 

32- bit integer 7-4 

double 7-3 

losing 7-3, 7-4 

real 7-4 

single 7-3 
Primary Segment 3-7, 7-1 

changing 3-7,7-1 

display 3-7, 7-1 

in hierarchy 3-7, 7-1 

instancing 3-7, 7-1 
Primitive 1-7, 4-1, 11-3 

circle 4-1 

curve 4- 1 

polyline 4- 1 

rectangle 4- 1 

user- defined 11-3 
Primitive command 1-3, 3-1 
Primitives 4- 1 
Printing 12-1 

file 12-1 

part of file 12-1 
Program example 

attribute classes and blocks 13-8, E-30, F-10 

attributes 5-5 

attributes and instancing 5-6, D-1, E-6, E-43, F-26 

C E-1 

changing the view 8-9, E-18 

color map and grid 14-6, E- 36, F- 19 

drawing a rectangle 3-9, E-1, F-1 
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FORTRAN F-1 

interactive functions 9-3, E-22 

locator events and cursor 10-20 

picking 10-13 

primitives and instancing 4-5, E-3, F-3 

stroke and pixel fonts 6-9, E-11 

stroke font 6-8 

tags 15-1 

tags and characters 6-9 

text 6-3, E-9, F-7 

user- defined primitive 11-4 

within- GPR mode 11-4 
Programming techniques 14-12 
Protecting 5- 1 
Puck 10-4 

Raster operation 5-3 

draw value 5-3 
Reading commands 10-21 
Real numbers 7-3 
Rectangle 1-3, 4-1, 5-5, 15-3 

rotation 15-3 

speed 15—3 
Redisplay 3- 1 
Refresh state 10-2 

and mode 10-2 

inhibiting 10-2 

partial 10-2 

updating 10-2 

viewport 10-2 

waiting 10-2 
See also Display 
Refreshing display 8-8 
Reusing 3-2, 4-3 

See also Instancing 
Rotating 2-3, 4-3, 15-3 
Routine, defined 1-3 
Rubberbanding 9-2, 9-3, 10-1 
Rubberbanding mode 9-2 

Scaling 1-2, 2-3, 4-3 

Screen 3-4 

Search 

See also Picking 
Search rules 10-8, 10-11 
command 10-11 
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segment 10"8 
Segment 1-2, 1-3, 3-1, 3-6, 3-7, 7-1, 11-1, 15-2, 15-5 

bounds 15-2 

characteristics 7-2 

closing 3-6 

copying 3-7 

counting 3-6 

creating 3-6 

current 3-6 

deleting 3-6, 3-7 

identifying 3-6 

naming 3-6 

opening 3-6 

primary 3-7,7-1 

renaming 3-6 

size 15-2 

temporary 15-5 

visibility 11-1 
Segment characteristics 7-2 

pickable 7-2 

temporary 7-2 

visible 7-2 
Segmentation 3-2 

hierarchical structure 3-2 

nested 1-2, 3-2 
Storage 1-2 

virtual 1-2 
Strategies for applications 1-13, 15-2 
Stroke font 6-6 

defaults 6-8 

defining characters 6-7 

example 6-8 

metafile 6-7 

tag definition 6-8 
Subroutine 1-3 

Tag 6-9 

Tag commands 1-3, 3-1, 6-7 

Tags 15-1 

inserting 15-1 

locating 15- 1 
Temporary segment 7-2 
Terminating 3-3, 3-5 
Text 1-1, 1-3, 6-1 

attributes 6-2 
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background value 5-1, 6°»2 

character 6-" 1 

direction 6" 1 

editor 1-6 

file 6-1 

font 6-1, 6-2 

inserting 6- 1 

size 5-1, 6-2 

value 5-1, 6-2 
Text editor 1-6 
Touchpad 10-4 
Transformation 1-2, 1-3, 4-5 

rotating 2-3 

scaling 2-3 

translation 2-3 
Transformation matrix 4-10 
Transformations 4- 10 
Translation 1-2, 2-3, 4-5 

User-defined primitive 11-3 

Vector graphics 1-1 
Vievy 1-2, 2-3, 8-8 

changing 8-8 

moving 2-3 

resetting 8-8 

scaling 2-3, 8-8 

transforming 8-8 

translating 8-8 
Viewing 1-3, 2-2, 3-2, 4-2, 13-6 

all of metafile 3-2 

and attributes 13-6 

routines 1-3, 1-6, 2-2 
Viewing transformations 2-3 
Viewport 1-2, 2-3, 4-2, 4-3, 8-4, 8-7 

border size 8-4 

creating 8-4 

current 4-3, 8-4, 8-7 

deleting 8-4 

multiple 8-4 

primary segment 8-2 

refreshing 8-8 

selecting 8-4 

setting bounds 8-4 
Visibility 7-2, 8-6 

criteria 8-5 
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mask 7-2, 8-5 
threshold 7-2, 8-5 
value 8-5 

Wildcard options 15-1 

Within- GPR mode 2-2, 3-4, 11-1 

Word processor 1-6 

World coordinates 2-6, 4-3 
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READER'S RESPONSE 



We use readers' comments in revising and improving our documents. 

Document Title: Programming With DOMAIN 2D Graphics Metafile Resource 

Order Number: 005097 

Revision: 00 

Date of Publication: July, 1985 

What is the best feature of this manual? 



Please list any errors, omissions, or problem areas in the manual. (Identify errors by page, 
section, figure, or table number wherever possible.) 



What type of user are you? 

Systems programmer; language 



Applications programmer; language 

Manager/Professional 

Technical Professional 

Adminstrative/Support Personnel 

Student programmer 

User with little programming experience 

Other 



How often do you use your system? 



Nature of your work on the DOMAIN System: 



Your name Date 



Organization 



Street Address 



City State Zip/Country 

No postage necessary if mailed in the U.S. Fold on dotted lines (see reverse), tape, and mail. 
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BUSINESS REPLY MAIL 

FIRST CLASS PERMIT NO. 78 CHELMSFORD, MA 01824 



POSTAGE WILL BE PAID BY ADDRESSEE 



APOLLO COMPUTER INC. 
Technical Publications 
P.0» Box 451 
Chelmsford, IVIA 01824 
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